add-note.api.mdx

id	add-note
title	Add note
description	Add a new note.
sidebar_label	Add note
hide_title	true
hide_table_of_contents	true
api	tags description parameters requestBody responses operationId method path servers security securitySchemes jsonRequestBodyExample info postman Notes Add a new note. content application/json schema example type properties required additionalProperties object body saveToQR attachedEntity ranges type minLength maxLength description example string 6 10000 The main content of the note, must be between the specified minimum and maximum length. This is a sample note body. type description example default boolean Indicates whether the note should be saved to the QuranReflect. true false type properties required additionalProperties object entityId entityType entityMetadata type description example string The unique identifier for the attached entity. entity123 type enum description example string reflection The type of the attached entity, must be one of the predefined NoteEntityType values. reflection type properties description example object Additional metadata for the attached entity. key value entityId entityType false type items description example array type pattern string ^(\d+):(\d+)-(\d+):(\d+)$ An array of verse ranges associated with the note. 2:255-2:257 body false body saveToQR attachedEntity ranges This is a sample note body. true entityId entityType entityMetadata entity123 reflection key value 2:255-2:257 200 400 401 403 404 422 429 500 502 503 504 description content headers Request has been handled successfully. application/json schema example type properties additionalProperties object success data type example boolean true type properties required additionalProperties object id createdAt updatedAt body source attachedEntities ranges type description example string The unique identifier of the note. asdasdqwe1231 type format description example string date-time The creation date of the note. 2023-01-21T07:28:13.023Z type format description example string date-time The last update date of the note. 2023-01-22T07:28:13.023Z type minLength maxLength description example string 6 10000 The main content of the note, must be between the specified minimum and maximum length. This is a sample note body. type description example string The source of the note. we23412312weq type items description array type properties required additionalProperties object entityId entityType entityMetadata type description example string The unique identifier for the attached entity. entity123 type enum description example string reflection The type of the attached entity, must be one of the predefined NoteEntityType values. reflection type properties description example object Additional metadata for the attached entity. key value entityId entityType false An array of attached entities associated with the note. type items description example array type pattern string ^(\d+):(\d+)-(\d+):(\d+)$ An array of verse ranges associated with the note. 2:255-2:257 id createdAt updatedAt body false false success data true id createdAt updatedAt body source attachedEntities ranges asdasdqwe1231 2023-01-21T07:28:13.023Z 2023-01-22T07:28:13.023Z This is a sample note body. we23412312weq entityId entityType entityMetadata entity123 reflection key value 2:255-2:257 X-Mutation-At description schema Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control. type example string 1731636500303 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 authPostV1Notes post /v1/notes 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 body saveToQR attachedEntity ranges This is a sample note body. true entityId entityType entityMetadata entity123 reflection key value 2:255-2:257 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 note content type Add a new note. text/plain path host query variable v1 notes {{baseUrl}} 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 note

Add a new note.

<TabItem label={"application/json"} value={"application/json-schema"}>

Details

<summary style={{"textAlign":"left"}}>Request Body<div style={{"textAlign":"left","marginLeft":"1rem"}}><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"body"} required={true} schemaName={"string"} qualifierMessage={"Possible values: >= 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."}}><SchemaItem collapsible={false} name={"saveToQR"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true,"default":false}}><SchemaItem collapsible={true} className={"schemaItem"}>

attachedEntity<span style={{"opacity":"0.6"}}> object

<div style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"entityId"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"}}><SchemaItem collapsible={false} name={"entityType"} required={true} schemaName={"string"} qualifierMessage={"Possible values: [reflection]"} schema={{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"}}><SchemaItem collapsible={true} className={"schemaItem"}>

entityMetadata<span style={{"opacity":"0.6"}}> object

<div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

Additional metadata for the attached entity.

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
= 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.
Array [
entityMetadata object
Additional metadata for the attached entity.
]

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