Account creation, email/password login, Google sign-in (browser redirect flow and mobile ID-token flow), password reset, and the current user's profile and profile picture. Successful logins return a JWT that must be sent as `Authorization: Bearer <token>` on authenticated requests.

Create, list and revoke personal API tokens. Tokens are attached to your user account and act with your permissions. These endpoints require a login session token (JWT) — an API token cannot be used to manage API tokens.

Browse, search, create and edit books. A book is a classical text stored as an ordered array of bilingual lines (Arabic, English, commentary, root words) embedded in the book document. Most error responses in this group are plain-text bodies rather than JSON.

Per-user bookmarks on book lines, with an optional note. A bookmark points at a line by its zero-based position (lineId) within the book, and is unique per user, book and line. All routes require authentication and only ever touch the caller's own bookmarks.

Text-to-speech audio for book lines. Audio is generated per line field (arabic, english, commentary) with an OpenAI TTS voice, stored as MP3 in S3 under the key bookId/lineId/field/voice_contentHash.mp3, and handed to clients either as a time-limited S3 presigned URL or as an MP3 stream proxied by the API. The content hash covers all of the line text plus the voice, so editing a line invalidates its cached audio. Generating audio is restricted to editors and admins; anonymous callers and members can only fetch audio that has already been generated for the current line content, and the listing and URL endpoints apply the same read-access rules as GET /books/:bookId (private and subscriber-only books require a token).

AI-generated multiple-choice quizzes for books. A quiz belongs to one book and holds a list of questions, each with exactly 4 options (one correct) and a rationale. Reading quizzes is public; generating, editing and deleting them is limited to editors and admins.

Private, sectioned study notes that live inside folders. Section bodies are stored as strings (the Sharh editor stores BlockNote JSON in them). Also includes web clipping into a note and importing whole books from the usul.ai library as notes.

Folders organise a user's notes. Every note belongs to exactly one folder, and folders are private to their owner.

Individual flashcards (front / back) that belong to a flashcard collection and are scheduled with an SM-2 style spaced-repetition algorithm. Cards are private to their owner.

Flashcard decks. A collection groups cards, carries per-deck daily review settings, and exposes study queues (due cards, new cards) and statistics. Collections are private to their owner.

Upload PDFs or page images for asynchronous OCR, poll job status, and read, search, edit, import and export the resulting digitized books ("BookTexts"). The flow is: POST /ocr uploads the file to S3, creates a pending BookText and enqueues an SQS job; an OCR worker posts pages and the final result back through the /ocr/result callbacks; clients poll GET /ocr/status/:jobId and then fetch the text with GET /ocr/text/:jobId or GET /ocr/books/:bookTextId. Page credits are deducted (and overage billed at $0.02/page) only when a job is reported as completed.

Library of uploaded documents and videos stored in S3, with metadata (title, author, tags, categories, visibility) kept in MongoDB. Files and videos share the same underlying File model. Authentication failures are answered by the auth middleware with plain-text bodies (401 no token, 403 invalid token or missing role, 404 when the token's user no longer exists).

Social feed: posts with image/video media, one-level threaded comments, likes, content reports, user profiles and follows. Every route in this group requires a logged-in user. Authentication failures are answered by the auth middleware with plain-text bodies (401 no token, 403 invalid token or missing role, 404 when the token's user no longer exists).

Creator monetization: applying to become a creator, managing the creator profile, Stripe Connect payouts onboarding, paid subscription tiers (1-3), gating books and notes behind a subscription tier, posting creator updates, subscribing to a creator via Stripe Checkout, and the public creator directory and creator pages.

Push notification device registration and the in-app notification inbox (list, unread count, mark as read) for the authenticated user.

Site-wide announcements published by the Sharh team. Clients can fetch the single currently active announcement; creating and managing announcements is restricted to administrators and is not part of the public API.

Submit suggestions, bug reports and content corrections to the Sharh team. Submission is open to everyone; reviewing and managing feedback is restricted to administrators and is not part of the public API.

Stripe-backed subscription management (checkout, cancel, reactivate, plan changes), payment methods, invoices, and OCR page-credit usage tracking. Every call acts on the Stripe customer attached to the authenticated user. Plans: $5/month (1,000 OCR pages per billing period), $10/month (2,000 pages) and $50/month (10,000 pages); pages beyond the plan allowance are billed as overage at $0.02 per page. Most errors in this group are returned as plain text, not JSON.

Mobile in-app purchase entitlements. Lets the iOS app validate an App Store subscription with Apple and attach it to the signed-in Sharh account, and lets any client read the account's current mobile subscription state.

Referral program. Affiliates are created by administrators and identified by a unique referral code; a referral links one signed-up user to one affiliate, and the affiliate earns a percentage commission (`commissionRate`) on that user's subscription payments. These endpoints let a signup flow validate a referral code and record the referral, and let an affiliate view their own performance. Affiliate management endpoints are admin-only and not documented here.