docs: add complete API reference entrypoint

docs/api-reference.mdx

@@ -0,0 +1,39 @@
+---
+title: "API Reference"
+description: "Choose the right Quran Foundation API reference for content, search, OAuth2, user features, and pre-live user API validation."
+sidebar_label: "API Reference"
+displayed_sidebar: "APIsSidebar"
+---
+
+# API Reference
+
+Use this page when you already know what you are building and need endpoint-level request and response details.
+
+If you do not have a Quran Foundation client yet, start with [Request Access](/request-access). If you are still choosing an app shape, start with the [Developer Journey](/docs/developer-journey).
+
+## API Families
+
+| API family | Use for | Authentication shape | Reference |
+| --- | --- | --- | --- |
+| Content APIs | Quran text, chapters, verses, translations, tafsir, audio, recitations, pages, juz, hizb, ruku, and manzil resources. | App credentials from your backend, or the JavaScript SDK server client. | [Open Content APIs](/docs/content_apis_versioned/4.0.0/content-apis/) |
+| Search APIs | Quran search queries and search result retrieval. | App credentials from your backend, or the JavaScript SDK server client. | [Open Search APIs](/docs/search_apis_versioned/1.0.0/quran-foundation-search-api/) |
+| User-related APIs | Bookmarks, collections, notes, reading sessions, goals, preferences, profiles, rooms, posts, comments, and tags. | OAuth2 user session token plus client ID. | [Open User-related APIs](/docs/user_related_apis_versioned/1.0.0/user-related-apis/) |
+| OAuth2 APIs | Authorization, token exchange, introspection, OIDC userinfo, and logout endpoints. | OAuth2 / OpenID Connect. | [Open OAuth2 APIs](/docs/oauth2_apis_versioned/1.0.0/oauth-2-apis/) |
+| User-related APIs (Pre-live) | Upcoming user API behavior before it is promoted to production docs. | Pre-live OAuth2 user session token plus client ID. | [Open Pre-live User APIs](/docs/category/user-related-apis-pre-live) |
+
+## Reference Helpers
+
+- [Field Reference](/docs/api/field-reference) lists common content field selectors.
+- [OAuth2 Scopes](/docs/user_related_apis_versioned/scopes) lists user API scopes.
+- [Content APIs Quickstart](/docs/quickstart) explains the first backend Content API call.
+- [User APIs Quickstart](/docs/tutorials/oidc/user-apis-quickstart) explains signed-in user API calls.
+
+## OpenAPI Specs
+
+| Spec | URL |
+| --- | --- |
+| Content APIs v4 | [`/openAPI/content/v4.json`](/openAPI/content/v4.json) |
+| Search APIs v1 | [`/openAPI/search/v1.json`](/openAPI/search/v1.json) |
+| User-related APIs v1 | [`/openAPI/user-related-apis/v1.json`](/openAPI/user-related-apis/v1.json) |
+| User-related APIs v1 (Pre-live) | [`/openAPI/user-related-apis/pre-live/v1.json`](/openAPI/user-related-apis/pre-live/v1.json) |
+| OAuth2 APIs v1 | [`/openAPI/oauth2-apis/v1.json`](/openAPI/oauth2-apis/v1.json) |

docs/developer-journey.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Developer Journey"
-description: "Choose the right Quran Foundation docs path for full apps, content-only integrations, signed-in user features, custom OAuth flows, and endpoint reference lookups."
+description: "Choose the right Quran Foundation docs path for request access, full apps, content-only integrations, signed-in user features, custom OAuth flows, and endpoint reference lookups."
 sidebar_label: "Developer Journey"
 displayed_sidebar: "APIsSidebar"
 ---
@@ -10,15 +10,16 @@ import AgentPromptCallout from "@site/src/components/AgentPromptCallout";
 
 # Developer Journey
 
-Use this page to choose the right starting point before jumping into endpoint reference pages.
+Use this page to request access, choose the right starting point, and avoid jumping into endpoint reference pages before the authentication shape is clear.
 
 <AgentPromptCallout />
 
 <DeveloperJourneyMap />
 
 ## Recommended Order
 
-1. Pick the path that matches your app shape.
-2. Set up the correct authentication flow.
-3. Use the JavaScript SDK when you are building with JavaScript or TypeScript.
-4. Move to endpoint reference pages only after the auth and runtime boundary are clear.
+1. Request access and confirm the client, redirect URI, and scopes your app needs.
+2. Pick the path that matches your app shape.
+3. Set up the correct authentication flow.
+4. Use the JavaScript SDK when you are building with JavaScript or TypeScript.
+5. Move to endpoint reference pages only after the auth and runtime boundary are clear.

docs/sdk/index.mdx

@@ -34,4 +34,4 @@ Our SDKs provide:
 
 ## Direct API Access
 
-If you prefer to use the API directly without an SDK, check out our [Content APIs Quickstart Guide](/docs/quickstart) and [API Reference](/docs/category/content-apis).
+If you prefer to use the API directly without an SDK, check out our [Content APIs Quickstart Guide](/docs/quickstart) and [API Reference](/docs/api-reference).

docusaurus.config.js

@@ -246,6 +246,10 @@ const config = {
             label: "APIs",
             position: "left",
             items: [
+              {
+                label: "API Reference",
+                to: "/docs/api-reference",
+              },
               {
                 label: "Content APIs",
                 to: "/docs/content_apis_versioned/4.0.0/content-apis/",
@@ -260,7 +264,7 @@ const config = {
               },
               {
                 label: "User-related APIs (Pre-live)",
-                to: "docs/category/user-related-apis-pre-live",
+                to: "/docs/category/user-related-apis-pre-live",
               },
               {
                 label: "OAuth2 APIs",
@@ -288,6 +292,10 @@ const config = {
           {
             title: "API Docs",
             items: [
+              {
+                label: "API Reference",
+                to: "/docs/api-reference",
+              },
               {
                 label: "Content APIs",
                 to: "/docs/content_apis_versioned/4.0.0/content-apis/",

plugins/llms-txt-plugin.js

@@ -29,6 +29,7 @@ const SECTION_ORDER = [
 
 const URL_PRIORITY = [
   `${BASE_URL}/docs/developer-journey`,
+  `${BASE_URL}/docs/api-reference`,
   `${BASE_URL}/docs/tutorials/oidc/starter-with-npx`,
   `${BASE_URL}/docs/sdk/javascript`,
   `${BASE_URL}/docs/sdk/javascript/app-shapes`,
@@ -66,6 +67,7 @@ const OPENAPI_HEADER = [
   '- [QF_NPX_STARTER_PROMPT_V1](https://api-docs.quran.foundation/agent-prompts/qf-next-starter.md): Copyable prompt for the official Next.js starter app',
   '- [Agent prompt registry](https://api-docs.quran.foundation/.well-known/agent-prompts/index.json): Machine-readable prompt catalog',
   '- [Developer Journey](https://api-docs.quran.foundation/docs/developer-journey/): Choose the right starting point by app shape',
+  '- [API Reference](https://api-docs.quran.foundation/docs/api-reference/): Choose between Content, Search, User-related, OAuth2, and pre-live endpoint references',
   '- [Starter With NPX](https://api-docs.quran.foundation/docs/tutorials/oidc/starter-with-npx/): One-command Next.js app scaffold',
   '- [JavaScript SDK](https://api-docs.quran.foundation/docs/sdk/javascript/): Runtime-split SDK guidance for public and server code',
   '',

sidebars.js

@@ -528,6 +528,11 @@ const makeSharedDocsSidebar = (apiFamilies) => [
     collapsible: true,
     collapsed: false,
     items: [
+      {
+        type: "doc",
+        id: "api-reference",
+        label: "API Reference",
+      },
       ...apiFamilies.map(makeSharedApiFamilyCategory),
       {
         type: "doc",

src/components/DeveloperJourneyMap/index.tsx

@@ -9,6 +9,12 @@ type Props = {
 };
 
 const journeyItems = [
+  {
+    title: "Request access",
+    body: "Get client credentials, confirm your redirect URIs, and make sure your app has the scopes it needs before implementation work starts.",
+    href: "/request-access",
+    cta: "Request Access",
+  },
   {
     title: "Full app with login",
     body: "Start from the production-shaped Next.js scaffold with reader, search, notes, bookmarks, OAuth2, and SDK wiring already in place.",
@@ -36,7 +42,7 @@ const journeyItems = [
   {
     title: "Endpoint lookup",
     body: "Go directly to endpoint reference pages once you know the API family and authentication model you need.",
-    href: "/docs/category/content-apis",
+    href: "/docs/api-reference",
     cta: "Browse API Reference",
   },
 ];
@@ -53,8 +59,9 @@ export default function DeveloperJourneyMap({ variant = "docs" }: Props) {
           <p className={styles.eyebrow}>Developer journey</p>
           <h2 className={styles.title}>Choose the shortest path to your integration</h2>
           <p className={styles.description}>
-            Start with the path that matches what you are building, then use
-            the API reference only after the authentication shape is clear.
+            Start by requesting access, then choose the path that matches what
+            you are building. Use the API reference after the authentication
+            shape is clear.
           </p>
         </div>
 

src/components/DeveloperJourneyMap/styles.module.css

@@ -43,7 +43,7 @@
 
 .grid {
   display: grid;
-  grid-template-columns: repeat(5, minmax(0, 1fr));
+  grid-template-columns: repeat(3, minmax(0, 1fr));
   gap: 0.85rem;
   margin: 0;
   padding: 0;
@@ -112,7 +112,7 @@
 
 @media (max-width: 1100px) {
   .grid {
-    grid-template-columns: repeat(3, minmax(0, 1fr));
+    grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 }
 

src/components/HomepageFeatures/index.tsx

@@ -15,21 +15,28 @@ const ApiCards: ApiCard[] = [
     icon: "📖",
     description:
       "Access Quranic chapters, verses, translations, audio files, and search through comprehensive endpoints designed for seamless app integration.",
-    link: "/docs/content_apis_versioned/content-apis",
+    link: "/docs/content_apis_versioned/4.0.0/content-apis/",
   },
   {
     title: "OAuth2 / OIDC APIs",
     icon: "🔐",
     description:
       "Implement secure user authentication using industry-standard OAuth2 and OpenID Connect flows. Manage tokens, authorization, and identity.",
-    link: "/docs/oauth2_apis_versioned/oauth-2-apis",
+    link: "/docs/oauth2_apis_versioned/1.0.0/oauth-2-apis/",
+  },
+  {
+    title: "Search APIs",
+    icon: "🔎",
+    description:
+      "Search Quran content through the dedicated search API surface. Use it when endpoint lookup is about query behavior rather than verse retrieval.",
+    link: "/docs/search_apis_versioned/1.0.0/quran-foundation-search-api/",
   },
   {
     title: "User-related APIs",
     icon: "👤",
     description:
       "Manage user data including bookmarks, reading sessions, preferences, goals, notes, and collections. Build personalized Quran experiences.",
-    link: "/docs/user_related_apis_versioned/user-related-apis",
+    link: "/docs/user_related_apis_versioned/1.0.0/user-related-apis/",
   },
 ];
 
@@ -54,10 +61,7 @@ export default function HomepageFeatures(): JSX.Element {
       <div className="container">
         <div className={styles.sectionHeader}>
           <h2 className={styles.sectionTitle}>Get started with our APIs:</h2>
-          <Link
-            className={styles.sectionLink}
-            to="/docs/content_apis_versioned/content-apis"
-          >
+          <Link className={styles.sectionLink} to="/docs/api-reference">
             See API References
           </Link>
         </div>

src/components/HomepageFeatures/styles.module.css

@@ -38,7 +38,7 @@
 /* ── Card grid ── */
 .cardGrid {
   display: grid;
-  grid-template-columns: repeat(3, 1fr);
+  grid-template-columns: repeat(4, 1fr);
   gap: 1.25rem;
 }
 

static/.well-known/agent-skills/index.json

@@ -6,7 +6,7 @@
       "type": "skill-md",
       "description": "Use Quran Foundation docs and tutorials to choose the correct API family, authentication flow, endpoint, font rendering approach, request-access prerequisite, and official references for content, search, OAuth2/OIDC, user-related, and Quran Reflect integrations.",
       "url": "/.well-known/agent-skills/quran-foundation-api-docs/SKILL.md",
-      "digest": "sha256:88c42b621a980cc7f4703da736583d16b8a6dec9b4b8482001cdb7f922dc34ba"
+      "digest": "sha256:1e41225d2b42a5c997a1aa4d670b817b0797c2f2a521c0b3915c8739200db741"
     }
   ]
 }

static/.well-known/agent-skills/quran-foundation-api-docs/SKILL.md

@@ -44,6 +44,7 @@ description: Use Quran Foundation docs and tutorials to choose the correct API f
 - Agent prompt registry: `https://api-docs.quran.foundation/.well-known/agent-prompts/index.json`
 - Next.js starter prompt: `https://api-docs.quran.foundation/agent-prompts/qf-next-starter.md`
 - Developer Journey: `https://api-docs.quran.foundation/docs/developer-journey/`
+- API Reference: `https://api-docs.quran.foundation/docs/api-reference/`
 - JavaScript SDK: `https://api-docs.quran.foundation/docs/sdk/javascript/`
 - Starter With NPX: `https://api-docs.quran.foundation/docs/tutorials/oidc/starter-with-npx/`
 - User APIs OIDC quickstart: `https://api-docs.quran.foundation/docs/tutorials/oidc/user-apis-quickstart/`
@@ -85,6 +86,7 @@ description: Use Quran Foundation docs and tutorials to choose the correct API f
 - "Bookmarks, collections, notes, reading sessions, profile, rooms, posts" -> User-related APIs v1
 - "Create a Quran app, starter app, scaffold, copy prompt, AI prompt, build with agents" -> Starter With NPX plus QF_NPX_STARTER_PROMPT_V1
 - "Where should I start, what path should I follow, developer journey" -> Developer Journey
+- "API reference, endpoint lookup, endpoint docs, all APIs" -> API Reference first, then the exact API family page
 - "JavaScript SDK, TypeScript SDK, server/public imports, runtime split" -> JavaScript SDK docs
 - "Web login flow, PKCE, callback, mobile auth, redirect URIs" -> OIDC tutorial pages plus OAuth2 APIs
 - "Fonts, glyph codes, Mushaf pages, script rendering, Tajweed display" -> Font rendering and page-layout tutorials plus relevant content endpoints

static/.well-known/mcp/server-card.json

@@ -45,6 +45,13 @@
       "description": "Starting-point guide for choosing between the starter app, Content APIs, User APIs, OAuth2, and API reference docs.",
       "mimeType": "text/html"
     },
+    {
+      "name": "api_reference",
+      "title": "API Reference",
+      "uri": "https://api-docs.quran.foundation/docs/api-reference/",
+      "description": "Landing page for choosing between Content, Search, User-related, OAuth2, and pre-live endpoint references.",
+      "mimeType": "text/html"
+    },
     {
       "name": "content_api_openapi",
       "title": "Content API OpenAPI",

static/llms.txt

@@ -15,12 +15,14 @@
 - [QF_NPX_STARTER_PROMPT_V1](https://api-docs.quran.foundation/agent-prompts/qf-next-starter.md): Copyable prompt for the official Next.js starter app
 - [Agent prompt registry](https://api-docs.quran.foundation/.well-known/agent-prompts/index.json): Machine-readable prompt catalog
 - [Developer Journey](https://api-docs.quran.foundation/docs/developer-journey/): Choose the right starting point by app shape
+- [API Reference](https://api-docs.quran.foundation/docs/api-reference/): Choose between Content, Search, User-related, OAuth2, and pre-live endpoint references
 - [Starter With NPX](https://api-docs.quran.foundation/docs/tutorials/oidc/starter-with-npx/): One-command Next.js app scaffold
 - [JavaScript SDK](https://api-docs.quran.foundation/docs/sdk/javascript/): Runtime-split SDK guidance for public and server code
 
 ## Getting Started
 
 - [Developer Journey](https://api-docs.quran.foundation/docs/developer-journey)
+- [API Reference](https://api-docs.quran.foundation/docs/api-reference)
 - [Field Reference](https://api-docs.quran.foundation/docs/api/field-reference)
 - [First Content API Call](https://api-docs.quran.foundation/docs/quickstart/first-api-call)
 - [Quran Foundation Content APIs OAuth2 Quickstart](https://api-docs.quran.foundation/docs/quickstart)