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/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 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..1b1efe55 --- /dev/null +++ b/docs/tutorials/sync/getting-started.mdx @@ -0,0 +1,163 @@ +--- +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=T
    { 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 `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 + +:::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. All `/v1/sync` calls also require the [`sync`](/docs/user_related_apis_versioned/scopes#sync) scope. + +| 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) | + +:::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 + +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 (no `lastMutationAt` stored on the server): + +| 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. +::: + +## Quick Start: Your First Sync + +```mermaid +flowchart TD + A[Start] --> B["GET /v1/sync?mutationsSince=0&metadataOnly=true"] + B --> C{lastMutationAt?} + 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=-1 (first time)
    or lastMutationAt=T (later)
    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. (You still need to pass `mutationsSince`, even when `metadataOnly=true`.) + +- `lastMutationAt: -1` means no sync history yet (first-sync state) +- 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 using `POST /v1/sync?lastMutationAt=...`. 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) + +## 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. +- **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 + +- [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..dba477da --- /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 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 + +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
    { mutations: [...] } + 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. You still need to pass `mutationsSince` in the request. + +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..601e1900 --- /dev/null +++ b/docs/tutorials/sync/offline-first-patterns.mdx @@ -0,0 +1,140 @@ +--- +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. Resource fields vary by type, so keep them in a data payload you can map into your domain model. + +```typescript +interface LocalResource> { + // Server fields + id: string; + resource: "BOOKMARK" | "COLLECTION" | "COLLECTION_BOOKMARK" | "NOTE"; + data: TData; + + // 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). + +### 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. + +## 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. 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 + +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/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..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":"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":"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,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. @@ -46,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 885ba7b5..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":[],"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":"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 @@ -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. @@ -46,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 b2d5d669..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":[],"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}}}},"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 @@ -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. @@ -58,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-or-update-preference.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx index 67eb0f20..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 @@ -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..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":[],"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":"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,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. @@ -46,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/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..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"}},"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},"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
              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}}>= 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..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 1098ff46..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 c924826a..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"],"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","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 @@ -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 b272fac8..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":"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":"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 96a5188e..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":"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":"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,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. @@ -46,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..284c22ce --- /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":"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 +--- + +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 24102104..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":"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":"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,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. @@ -46,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 b4da3471..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":"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":"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,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. @@ -46,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 975b1901..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."}],"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}}}},"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 @@ -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. @@ -46,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 28fc44f0..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":"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":"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 5e455206..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":"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":"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 a6487da8..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":"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":"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 c34d48d1..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":"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":"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 f558da8a..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":"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":"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 d36b7510..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":"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":"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 a78a9746..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":"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":"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 4e80752a..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":"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":"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-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx new file mode 100644 index 00000000..4cfd066a --- /dev/null +++ b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx @@ -0,0 +1,94 @@ +--- +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,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 +--- + +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. + +
    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 + +
      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
    + +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. + +
    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..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":"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":"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 cae78204..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":"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":"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 19ef92cd..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"],"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","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 @@ -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 76db9ab0..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":"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":"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 6c6d476f..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"}},"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},"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
      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}}>= 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..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":"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":"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 a7c2f3ea..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-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-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 d5e2ac5d..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-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-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 ec85f582..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 d621d6db..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 588d039a..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 db73368e..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 be007927..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 cf262e3f..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 07e3b0e9..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/publish-note.api.mdx b/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx index b0221f38..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."}],"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}}}},"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 @@ -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. @@ -50,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/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/sidebar.js b/docs/user_related_apis_versioned/1.0.0/sidebar.js index 62ae72a2..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":"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-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 new file mode 100644 index 00000000..a8027430 --- /dev/null +++ b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx @@ -0,0 +1,98 @@ +--- +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 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 +--- + +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. + +
        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 + +
          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. Client must re-sync data before retrying this operation. + +
        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..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 56f6aa30..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":"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":"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 @@ -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 9bef99bc..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."}],"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}}}},"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 @@ -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. @@ -46,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 726b625f..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."}],"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}}}},"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 @@ -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. @@ -54,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/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 f1ba7518..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":"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":"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,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. @@ -46,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 2c26dd54..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":[],"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":"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 @@ -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. @@ -46,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 9641c405..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":[],"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}}}},"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 @@ -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. @@ -58,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-or-update-preference.api.mdx b/docs/user_related_apis_versioned/add-or-update-preference.api.mdx index df6c4e88..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 @@ -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..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":[],"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":"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,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. @@ -46,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/bulk-add-or-update-preferences.api.mdx b/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx index 2c4ff822..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"}},"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},"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
                      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}}>= 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..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 330f08f6..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 9686e885..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"],"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","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 @@ -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 dfb8e73b..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":"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":"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 a45b9984..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":"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":"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,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. @@ -46,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..d82c9f8c --- /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":"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 +--- + +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 819b1ab8..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":"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":"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,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. @@ -46,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 5beb75bd..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":"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":"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,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. @@ -46,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 6233d25d..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."}],"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}}}},"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 @@ -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. @@ -46,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 7e4d7d7f..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":"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":"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 8eb9735e..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":"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":"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 a60e9b90..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":"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":"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 6ea1992d..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":"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":"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 d5188d00..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":"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":"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 cf031d80..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":"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":"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 b99dd858..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":"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":"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 f13e31f5..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":"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":"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-mutations.api.mdx b/docs/user_related_apis_versioned/get-mutations.api.mdx new file mode 100644 index 00000000..bd11cd0a --- /dev/null +++ b/docs/user_related_apis_versioned/get-mutations.api.mdx @@ -0,0 +1,94 @@ +--- +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,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 +--- + +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. + +
            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 + +
              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
            + +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. + +
            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..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":"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":"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 5b77900b..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":"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":"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 1ba2e9ec..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"],"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","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 @@ -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 450c5ce8..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":"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":"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 65c7fd5a..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"}},"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},"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
      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}}>= 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..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":"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":"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 5e911853..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-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-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 ce3dd9fc..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-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-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 69d0d5a7..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 b16875b5..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 4cf50120..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 388cf295..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 fc48e22e..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 2ed910f9..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 7ea93bc3..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/publish-note.api.mdx b/docs/user_related_apis_versioned/publish-note.api.mdx index 7dbf10ef..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."}],"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}}}},"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 @@ -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. @@ -50,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/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/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. | diff --git a/docs/user_related_apis_versioned/sidebar.js b/docs/user_related_apis_versioned/sidebar.js index 524704a3..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":"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-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 new file mode 100644 index 00000000..d9da4517 --- /dev/null +++ b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx @@ -0,0 +1,98 @@ +--- +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 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 +--- + +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. + +
        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 + +
          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. Client must re-sync data before retrying this operation. + +
        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..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 265f7835..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":"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":"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 @@ -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 32c449d5..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."}],"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}}}},"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 @@ -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. @@ -46,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 64f89202..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."}],"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}}}},"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 @@ -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. @@ -54,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/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 eb02a60b..0303327a 100644 --- a/openAPI/user-related-apis/v1.json +++ b/openAPI/user-related-apis/v1.json @@ -1 +1,18184 @@ -{"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": "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 + }, + "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 + }, + "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 + }, + "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 + }, + "ReadingSession": { + "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 + }, + "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" }, + "hideFollowSuggestion": { + "type": "boolean", + "description": "Hide follow suggestion popup after liking a post" + } + } + }, + "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 + } + } + } + }, + "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 + } + } + } + } + } + }, + "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": "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": { "$ref": "#/components/schemas/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 + } + } + } + } + } + } + }, + "/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": "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", + "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 + } + } + } + }, + "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 + } + } + } + } + } + }, + "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": "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", + "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" + }, + { + "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" + }, + { + "type": "object", + "properties": { + "bookmarkId": { + "type": "string", + "description": "The Id of the bookmark to be deleted.", + "example": "cmllufwbz000a42jq38zw6ymi" + } + }, + "required": ["bookmarkId"], + "additionalProperties": false, + "title": "Bookmark ID" + } + ], + "title": "input" + } + } + } + } + } + }, + "/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": "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 + } + } + } + } + } + }, + "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": "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": { + "$ref": "#/components/schemas/Collection" + }, + "bookmarks": { + "type": "array", + "items": { "$ref": "#/components/schemas/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 + } + } + } + } + } + }, + "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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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": "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 + } + } + } + } + } + } + }, + "/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": "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": { "$ref": "#/components/schemas/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 + } + } + } + } + } + } + }, + "/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 + }, + "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], + "description": "The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \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" + }, + "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], + "description": "The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \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 + } + } + } + }, + "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 + } + } + } + } + } + }, + "get": { + "description": "Get all bookmarks. This includes bookmarks belonging to a collection.", + "tags": ["Bookmarks"], + "summary": "Get user bookmarks", + "parameters": [ + { + "in": "query", + "name": "type", + "schema": { + "type": "string", + "enum": ["page", "juz", "surah", "ayah"], + "description": "The bookmark type.", + "default": "ayah" + }, + "required": false, + "description": "The bookmark type." + }, + { + "in": "query", + "name": "isReading", + "schema": { + "type": "boolean", + "description": "Whether to fetch only the reading bookmark" + }, + "required": false, + "description": "Whether to fetch only the reading bookmark" + }, + { + "in": "query", + "name": "key", + "schema": { + "type": "integer", + "description": "Filter by key (surah/juz/page number)" + }, + "required": false, + "description": "Filter by key (surah/juz/page number)" + }, + { + "in": "query", + "name": "mushafId", + "schema": { + "type": "integer", + "enum": [1, 2, 3, 4, 5, 6, 7, 11, 19], + "description": "The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4", + "example": 4 + }, + "required": true, + "description": "The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4" + }, + { + "in": "query", + "name": "last", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "description": "The number of items to be fetched. Should be used together with `before`", + "example": 10 + }, + "required": false, + "description": "The number of items to be fetched. Should be used together with `before`" + }, + { + "in": "query", + "name": "first", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 20, + "oneOf": [{ "type": "integer" }], + "description": "The number of items to be fetched.", + "example": 10 + }, + "required": false, + "description": "The number of items to be fetched." + }, + { + "in": "query", + "name": "after", + "schema": { + "type": "string", + "oneOf": [{ "type": "string" }], + "description": "The cursor after which you want to get the next page of items. Should be used together with `first`", + "example": "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": { "$ref": "#/components/schemas/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 + } + } + } + } + } + } + }, + "/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": "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 + } + } + } + } + } + } + }, + "/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": "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 + } + } + } + } + } + } + }, + "/v1/bookmarks/bookmark": { + "get": { + "description": "Get a bookmark by details", + "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": 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": { "$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": "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": { "$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", + "surahInfoFontScale", + "hadithFontScale", + "quranFont", + "mushafLines", + "showTajweedRules" + ] + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "enum": ["selectedTranslations"] + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { "type": "string", "enum": ["selectedTafsirs"] } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "enum": [ + "reciter", + "playbackRate", + "showTooltipWhenPlayingAudio", + "enableAutoScrolling", + "repeatSettings" + ] + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { "type": "string", "enum": ["language"] } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "string", + "enum": [ + "en", + "ar", + "bn", + "fa", + "fr", + "id", + "it", + "nl", + "pt", + "ru", + "sq", + "th", + "tr", + "ur", + "zh", + "ms", + "es", + "sw", + "vi" + ] + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "string", + "enum": ["auto", "light", "sepia", "dark"], + "example": "auto" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "string", + "enum": [ + "translation", + "reading", + "readingTranslation" + ], + "example": "translation" + } + }, + "required": ["value"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "string", + "enum": [ + "en", + "ur", + "id", + "bn", + "tr", + "fa", + "ru", + "hi", + "de", + "ta", + "inh", + "fr", + "sq", + "dv", + "zh", + "sd", + "ml" + ], + "example": "en" + } + }, + "required": ["value"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "string", + "enum": ["play-audio", "no-audio"], + "example": "play-audio" + } + }, + "required": ["value"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { "type": "boolean", "example": true } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "array", + "items": { + "type": "string", + "enum": ["translation", "transliteration"] + }, + "example": ["translation"] + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "array", + "items": { + "type": "string", + "enum": ["tooltip", "inline"] + }, + "example": ["tooltip"] + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "array", + "items": { + "type": "string", + "enum": ["translation", "transliteration"] + }, + "example": [] + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "string", + "enum": [ + "code_v1", + "code_v2", + "text_uthmani", + "text_indopak", + "qpc_uthmani_hafs", + "tajweed", + "tajweed_v4" + ], + "example": "code_v1" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "string", + "enum": ["15_lines", "16_lines"], + "example": "16_lines" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "integer", + "minimum": 1, + "maximum": 10, + "example": 3 + } + }, + "required": ["value"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "integer", + "minimum": 1, + "maximum": 6, + "example": 3 + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "array", + "items": { "type": "integer", "example": 131 } + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "array", + "items": { + "type": "string", + "example": "en-tafisr-ibn-kathir" + } + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "integer", + "enum": [0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2], + "example": 1 + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { "type": "boolean", "example": false } + }, + "required": ["value"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { "type": "string", "enum": ["userHasCustomised"] } + }, + "required": ["key"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "string", + "minLength": 1, + "maxLength": 255, + "example": "131" + } + }, + "required": ["value"], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "value": { + "type": "array", + "items": { "type": "string", "maxLength": 10 }, + "minItems": 1 + } + }, + "required": ["value"], + "additionalProperties": false + } + ] + } + } + } + }, + "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": "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": { "$ref": "#/components/schemas/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 + } + } + } + } + } + } + }, + "/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", + "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 + } + } + } + } + } + } + }, + "/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": "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 + } + } + } + } + } + }, + "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": "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 + } + } + } + } + } + } + }, + "/v1/goals": { + "post": { + "description": "Create a goal", + "tags": ["Goals"], + "summary": "Create a goal", + "parameters": [ + { + "in": "query", + "name": "mushafId", + "schema": { + "type": "integer", + "enum": [1, 2, 3, 4, 5, 6, 7, 11, 19], + "description": "The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4", + "example": 4 + }, + "required": true, + "description": "The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4" + }, + { + "in": "header", + "name": "x-timezone", + "schema": { + "type": "string", + "description": "The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.", + "example": "Asia/Saigon" + }, + "description": "The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "QURAN_TIME", + "QURAN_PAGES", + "QURAN_RANGE", + "COURSE", + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" + ], + "description": "The type of the goal.", + "example": "QURAN_TIME" + }, + "amount": { + "oneOf": [ + { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$", + "example": "1:5-1: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 + } + } + } + } + } + } + }, + "/v1/goals/estimate": { + "get": { + "description": "Generate a timeline up to a week of the minimum daily amount required to meet the goal.", + "tags": ["Goals"], + "summary": "Generate timeline estimation", + "parameters": [ + { + "in": "query", + "name": "type", + "schema": { + "type": "string", + "enum": [ + "QURAN_TIME", + "QURAN_PAGES", + "QURAN_RANGE", + "COURSE", + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" + ], + "description": "The type of the goal.", + "example": "QURAN_TIME" + }, + "required": true, + "description": "The type of the goal." + }, + { + "in": "query", + "name": "amount", + "schema": { + "oneOf": [ + { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$", + "example": "1:5-1: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": "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 + } + } + } + } + } + } + }, + "/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": "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 + } + } + } + } + } + } + }, + "/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": "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 + } + } + } + } + } + }, + "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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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": "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 + } + } + } + } + } + } + }, + "/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 + } + } + } + }, + "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 + } + } + } + } + } + }, + "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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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,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 + } + } + } + } + } + }, + "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 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 + } + } + } + } + } + } + }, + "/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" + } + }, + { + "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" + } + ] + } + }, + "/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" + } + }, + { + "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" + } + ] + } + }, + "/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" + } + ] + } + } + } +} 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: [ {