User-related API environment

Pre-live user-related API docs

These pages describe the Pre-live user-related API stack.

Use pre-live OAuth credentials, pre-live API base URLs, and pre-live app URLs when following this documentation. Keep your OAuth flow, API requests, callback URLs, and manual testing within the pre-live environment.

• Use prelive.quran.com for auth-related testing.
• Use prelive.quranreflect.org for Quran Reflect paths where applicable.
• Do not mix production sessions or production user data with pre-live testing.

Add note

Add a new note.

application/json

Request Body

body string required

Possible values: >= 6 characters and <= 10000 characters

The main content of the note, must be between the specified minimum and maximum length.

saveToQR boolean

Default value: false

Indicates whether the note should be saved to the QuranReflect.

attachedEntity object

entityId string required

The unique identifier for the attached entity.

entityType string required

Possible values: [reflection]

The type of the attached entity, must be one of the predefined NoteEntityType values.

entityMetadata object

Additional metadata for the attached entity.

ranges string[]

Possible values: Value must match regular expression ^(\d+):(\d+)-(\d+):(\d+)$

An array of verse ranges associated with the note.

clientCreatedAt object

Client-local timestamp when this resource was created. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.

oneOf

string

---

string

Client-local timestamp when this resource was created. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.

clientUpdatedAt object

Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.

oneOf

string

---

string

Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.

Responses

• 200
• 400
• 401
• 403
• 404
• 422
• 429
• 500
• 502
• 503
• 504

---

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.

application/json

Schema

Example (from schema)

Example

---

Schema

success boolean
data object

id string required

The unique identifier of the note.

createdAt date-time required

The creation date of the note.

updatedAt date-time required

The last update date of the note.

body string required

Possible values: >= 6 characters and <= 10000 characters

The main content of the note, must be between the specified minimum and maximum length.

source string

The source of the note.

attachedEntities object[]

An array of attached entities associated with the note.

Array [

entityId string required

The unique identifier for the attached entity.

entityType string required

Possible values: [reflection]

The type of the attached entity, must be one of the predefined NoteEntityType values.

entityMetadata object

Additional metadata for the attached entity.

]

ranges string[]

Possible values: Value must match regular expression ^(\d+):(\d+)-(\d+):(\d+)$

An array of verse ranges associated with the note.

{
  "success": true,
  "data": {
    "id": "asdasdqwe1231",
    "createdAt": "2023-01-21T07:28:13.023Z",
    "updatedAt": "2023-01-22T07:28:13.023Z",
    "body": "This is a sample note body.",
    "source": "we23412312weq",
    "attachedEntities": [
      {
        "entityId": "entity123",
        "entityType": "reflection",
        "entityMetadata": {
          "key": "value"
        }
      }
    ],
    "ranges": [
      "2:255-2:257"
    ]
  }
}

{
  "success": true,
  "data": {
    "id": "asdasdqwe1231",
    "createdAt": "2023-01-21T07:28:13.023Z",
    "updatedAt": "2023-01-22T07:28:13.023Z",
    "body": "This is a sample note body.",
    "source": "we23412312weq",
    "attachedEntities": [
      {
        "entityId": "entity123",
        "entityType": "reflection",
        "entityMetadata": {
          "key": "value"
        }
      }
    ],
    "ranges": [
      "2:255-2:257"
    ]
  }
}

The request is missing required parameters or is invalid.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The request is missing required headers or is invalid",
  "type": "invalid_request",
  "success": false
}

{
  "message": "The request is missing required headers or is invalid",
  "type": "invalid_request",
  "success": false
}

The request is unauthorized.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The request requires user authentication",
  "type": "unauthorized",
  "success": false
}

{
  "message": "The request requires user authentication",
  "type": "unauthorized",
  "success": false
}

Forbidden error. 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

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server understood the request, but refuses to authorize it",
  "type": "forbidden",
  "success": false
}

{
  "message": "The server understood the request, but refuses to authorize it",
  "type": "forbidden",
  "success": false
}

Not Found. The resource being accessed does not exist.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The requested resource could not be found",
  "type": "not_found",
  "success": false
}

{
  "message": "The requested resource could not be found",
  "type": "not_found",
  "success": false
}

Validation Error. The request includes one or more invalid params. Please check the request params and try again.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The request was well-formed but was unable to be followed due to semantic errors",
  "type": "unprocessable_entity",
  "success": false
}

{
  "message": "The request was well-formed but was unable to be followed due to semantic errors",
  "type": "unprocessable_entity",
  "success": false
}

Too many requests, please try again later.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "Too many requests, please try again later",
  "type": "rate_limit_exceeded",
  "success": false
}

{
  "message": "Too many requests, please try again later",
  "type": "rate_limit_exceeded",
  "success": false
}

Server Error. Something went wrong, try again later.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server encountered an internal error and was unable to complete your request",
  "type": "internal_server_error",
  "success": false
}

{
  "message": "The server encountered an internal error and was unable to complete your request",
  "type": "internal_server_error",
  "success": false
}

Invalid response from the upstream server

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server was acting as a gateway or proxy and received an invalid response from the upstream server",
  "type": "bad_gateway",
  "success": false
}

{
  "message": "The server was acting as a gateway or proxy and received an invalid response from the upstream server",
  "type": "bad_gateway",
  "success": false
}

The server is currently unable to handle the request due to a temporary overload or scheduled maintenance

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance",
  "type": "service_unavailable",
  "success": false
}

{
  "message": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance",
  "type": "service_unavailable",
  "success": false
}

The server did not receive a timely response from the upstream server.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server",
  "type": "gateway_timeout",
  "success": false
}

{
  "message": "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server",
  "type": "gateway_timeout",
  "success": false
}

Loading...