add-or-update-preference.api.mdx

id	add-or-update-preference
title	Add or update preference
description	Add or update one user preferences group like favorite Tafsirs or translations.
sidebar_label	Add or update preference
hide_title	true
hide_table_of_contents	true
api	description tags parameters requestBody responses operationId method path servers security securitySchemes jsonRequestBodyExample info postman Add or update one user preferences group like favorite Tafsirs or translations. Preferences in name schema required description query mushafId type enum description example integer 1 2 3 4 5 6 7 11 19 The id of the Mushaf being used. 1 = QCFV2 2 = QCFV1 3 = Indopak 4 = UthmaniHafs 5 = KFGQPCHAFS 6 = Indopak15Lines 7 = Indopak16Lines 11 = Tajweeed 19 = QCFTajweedV4 4 true The id of the Mushaf being used. 1 = QCFV2 2 = QCFV1 3 = Indopak 4 = UthmaniHafs 5 = KFGQPCHAFS 6 = Indopak15Lines 7 = Indopak16Lines 11 = Tajweeed 19 = QCFTajweedV4 content application/json schema example type properties required additionalProperties oneOf object group key value type enum description example string tafsirs translations audio theme quranReaderStyles reading language userHasCustomised The preference group to be added or updated. tafsirs type description example string The preference key to be added or updated. selectedTafsirs description example The preference value to be added or updated. ["en-tafisr-ibn-kathir"] group key value false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type required additionalProperties object value false type required additionalProperties object value false type required additionalProperties object value false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type required additionalProperties object value false type additionalProperties object false type additionalProperties object false type additionalProperties object false type additionalProperties object false type required additionalProperties object value false type required additionalProperties object key false type required additionalProperties object value false type required additionalProperties object value false key type 200 400 401 403 404 422 429 500 502 503 504 description content Request has been handled successfully. application/json schema example type properties additionalProperties object success data type example boolean true type properties additionalProperties object message enum preference updated false false success data true message preference updated description content The request is missing required parameters or is invalid. application/json schema type properties additionalProperties object message type success type example string The request is missing required headers or is invalid type example string invalid_request type example boolean false false description content The request is unauthorized. application/json schema type properties additionalProperties object message type success type example string The request requires user authentication type example string unauthorized type example boolean false false description content Forbidden error. Can either be due to access token not being passed, having been expired or the caller trying to access a resource without enough permissions. application/json schema type properties additionalProperties object message type success type example string The server understood the request, but refuses to authorize it type example string forbidden type example boolean false false description content Not Found. The resource being accessed does not exist. application/json schema type properties additionalProperties object message type success type example string The requested resource could not be found type example string not_found type example boolean false false description content Validation Error. The request includes one or more invalid params. Please check the request params and try again. application/json schema type properties additionalProperties object message type success type example string The request was well-formed but was unable to be followed due to semantic errors type example string unprocessable_entity type example boolean false false description content Too many requests, please try again later. application/json schema type properties additionalProperties object message type success type example string Too many requests, please try again later type example string rate_limit_exceeded type example boolean false false description content Server Error. Something went wrong, try again later. application/json schema type properties additionalProperties object message type success type example string The server encountered an internal error and was unable to complete your request type example string internal_server_error type example boolean false false description content Invalid response from the upstream server application/json schema type properties additionalProperties object message type success type example string The server was acting as a gateway or proxy and received an invalid response from the upstream server type example string bad_gateway type example boolean false false description content The server is currently unable to handle the request due to a temporary overload or scheduled maintenance application/json schema type properties additionalProperties object message type success type example string The server is currently unable to handle the request due to a temporary overload or scheduled maintenance type example string service_unavailable type example boolean false false description content The server did not receive a timely response from the upstream server. application/json schema type properties additionalProperties object message type success type example string The server was acting as a gateway or proxy and did not receive a timely response from the upstream server type example string gateway_timeout type example boolean false false authPostV1Preferences post /v1/preferences url description https://apis-prelive.quran.foundation/auth Pre-production Server url description https://apis.quran.foundation/auth Production Server x-auth-token x-client-id x-auth-token x-client-id type in name description apiKey header x-auth-token The JWT access token required for accessing the endpoints. type in name description apiKey header x-client-id Your client id group key value tafsirs selectedTafsirs ["en-tafisr-ibn-kathir"] title version description User-related APIs 1.0.0 Quran.Foundation user-related APIs enable your app to seamlessly integrate with Quran.Foundation's user-centric features, providing access to personalized notes, bookmarks, goals, streaks, reading sessions, and more. This differentiates them from [content APIs](/docs/category/content-apis) that focus on non-user-specific resources like translations, tafsirs, and verses. ## How to get access We are using OAuth2 flows to authenticate and authorize requests. To get started, you need to [get an access token](/docs/tutorials/oidc/getting-started-with-oauth2#obtaining-oauth-20-client-credentials) to make requests to our APIs. Then follow the steps mentioned [here](/docs/tutorials/oidc/getting-started-with-oauth2). For web applications, the recommended integration pattern is backend token exchange plus backend or server-side proxy calls to User APIs. Your app can keep the user session in secure server storage or `httpOnly` cookies, while your backend injects `x-auth-token` and `x-client-id` on outbound requests to Quran.Foundation APIs. ## Pagination We are using cursor based pagination. The pagination query params consist of `first`,`after`, `before` and `last`. Example - `first: 10` will give you first 10 items - `first: 10, after: xyz` will give you first 10 items after the item with id `xyz` - `last: 10` will give you the last 10 items - `last: 10, before: xyz` will give you the last 10 items before the item with id `xyz` The only possible combinations are `first + after` or `last + before`. They should not be used together name description url header method body Add or update preference content type Add or update one user preferences group like favorite Tafsirs or translations. text/plain path host query variable v1 preferences {{baseUrl}} disabled description key value false content type (Required) The id of the Mushaf being used. 1 = QCFV2 2 = QCFV1 3 = Indopak 4 = UthmaniHafs 5 = KFGQPCHAFS 6 = Indopak15Lines 7 = Indopak16Lines 11 = Tajweeed 19 = QCFTajweedV4 text/plain mushafId key value Content-Type application/json key value Accept application/json POST mode raw options raw "" raw language json
sidebar_class_name	post api-method
info_path	docs/user_related_apis_prelive/user-related-apis
custom_edit_url
displayed_sidebar	APIsSidebar

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";

Add or update preference

Add or update one user preferences group like favorite Tafsirs or translations.

Query Parameters

Request Body

oneOf= 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.

Schema

data object

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