diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
index e083d23d997..a83d4bec82b 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -758,6 +758,26 @@ export const reference_cli = {
     },
   ],
 }
+export const reference_api = {
+  icon: '/img/icons/api-icon.svg',
+  title: 'Mangement API',
+  url: '/guides/reference/api',
+  parent: '/reference',
+  items: [
+    {
+      name: 'Getting Started',
+      items: [
+        {
+          name: 'fake link',
+          href: '/reference/javascript/start',
+          level: 'reference_javascript',
+          items: [],
+          icon: '/img/icons/javascript.svg',
+        },
+      ],
+    },
+  ],
+}
 
 // export const reference: [
 //   {
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx
index 61542243d3a..ac847ac0cd1 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx
@@ -12,6 +12,20 @@ import { NavigationMenuContextProvider } from './NavigationMenu.Context'
 import jsSpecNEW from '~/../../spec/supabase_js_v2_temp_new_shape.yml' assert { type: 'yml' }
 // @ts-expect-error
 import dartSpecNEW from '~/../../spec/supabase_dart_v1_temp_new_shape.yml' assert { type: 'yml' }
+import apiSpecRaw from '~/../../spec/transforms/api_v0_openapi_deparsed.json' assert { type: 'json' }
+
+import libCommonSections from '~/../../spec/common-client-libs-sections.json'
+import cliCommonSections from '~/../../spec/common-cli-sections.json'
+import apiCommonSections from '~/../../spec/common-api-sections.json'
+
+// import { gen_v3 } from '~/lib/refGenerator/helpers'
+
+export type RefIdOptions =
+  | 'reference_javascript'
+  | 'reference_dart'
+  | 'reference_cli'
+  | 'reference_api'
+export type RefKeyOptions = 'javascript' | 'dart' | 'cli' | 'api'
 
 const SideNav = () => {
   const router = useRouter()
@@ -63,6 +77,9 @@ const SideNav = () => {
       case url.includes(`/docs/reference/cli`) && url:
         setLevel('reference_cli')
         break
+      case url.includes(`/docs/reference/api`) && url:
+        setLevel('reference_api')
+        break
 
       default:
         break
@@ -202,6 +219,11 @@ const SideNav = () => {
     ],
   ]
 
+  // generate Open API specs
+
+  // @ts-ignore
+  // const apiSpec = gen_v3(apiSpecRaw, 'wat', { apiUrl: 'apiv0' })
+
   return (
     <div className="flex relative">
       {/* // main menu */}
@@ -289,17 +311,30 @@ const SideNav = () => {
         key={'reference-js-menu'}
         id={'reference_javascript'}
         currentLevel={level}
-        setLevel={setLevel}
-        lib="js"
+        commonSections={libCommonSections}
+        lib="javascript"
       />
       <NavigationMenuRefList
         key={'reference-dart-menu'}
         id={'reference_dart'}
         currentLevel={level}
-        setLevel={setLevel}
+        commonSections={libCommonSections}
         lib="dart"
       />
-      <NavigationMenuCliList id={'reference_cli'} currentLevel={level} setLevel={setLevel} />
+      <NavigationMenuRefList
+        key={'reference-cli-menu'}
+        id={'reference_cli'}
+        currentLevel={level}
+        commonSections={cliCommonSections}
+        lib="cli"
+      />
+      <NavigationMenuRefList
+        key={'reference-api-menu'}
+        id={'reference_api'}
+        currentLevel={level}
+        commonSections={apiCommonSections}
+        lib="api"
+      />
     </div>
   )
 }
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenuRefList.tsx b/apps/docs/components/Navigation/NavigationMenu/NavigationMenuRefList.tsx
index cdd02ff0eb0..439faed0e02 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenuRefList.tsx
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenuRefList.tsx
@@ -7,17 +7,17 @@ import * as NavItems from './NavigationMenu.constants'
 import { find } from 'lodash'
 import Image from 'next/image'
 import { memo } from 'react'
-import clientLibsCommonSections from '~/../../spec/common-client-libs-sections.json'
+
+// import apiCommonSections from '~/../../spec/common-client-libs-sections.json'
+
 import RevVersionDropdown from '~/components/RefVersionDropdown'
 import { useMenuActiveRefId } from '~/hooks/useMenuState'
-
-const allFunctions = clientLibsCommonSections
+import { RefIdOptions, RefKeyOptions } from './NavigationMenu'
 
 const FunctionLink = ({
   title,
   id,
   icon,
-  product,
   library,
   slug,
 }: {
@@ -30,7 +30,6 @@ const FunctionLink = ({
   slug: string
 }) => {
   const router = useRouter()
-  // const { activeRefItem } = useNavigationMenuContext()
   const activeAccordianItem = useMenuActiveRefId()
 
   const active = activeAccordianItem === id
@@ -63,34 +62,56 @@ const Divider = () => {
   return <div className="h-px w-full bg-blackA-300 dark:bg-whiteA-300 my-3"></div>
 }
 
-const NavigationMenuRefList = ({ currentLevel, setLevel, id, lib }) => {
+interface INavigationMenuRefList {
+  currentLevel: string
+
+  id: RefIdOptions
+  lib: RefKeyOptions
+  commonSections: any[] // to do type up
+}
+
+const NavigationMenuRefList: React.FC<INavigationMenuRefList> = ({
+  currentLevel,
+
+  id,
+  lib,
+  commonSections,
+}) => {
   const router = useRouter()
 
-  const allCurrentFunctions = allFunctions
-  // .map((fn: any) => {
-  //   if (fn.items.flat().find((item) => item.libs.includes(lib))) return fn
-  // })
-  // .filter((item) => item)
+  let sections = commonSections
 
-  // const introItems = Object.values(clientLibsCommonSections.sections.intro[lib].items)
+  // console.log('sections', sections)
+  if (!sections) console.error('no common sections imported')
 
   const menu = NavItems[id]
 
-  const databaseFunctions = find(allFunctions, { title: 'Database' }).items
+  const databaseFunctions = find(sections, { title: 'Database' })
+    ? find(sections, { title: 'Database' }).items
+    : []
 
-  const filterIds = find(databaseFunctions, {
-    id: 'using-filters',
-  }).items.map((x) => x.id)
+  const filterIds =
+    databaseFunctions.length > 0
+      ? find(databaseFunctions, {
+          id: 'using-filters',
+        }) &&
+        find(databaseFunctions, {
+          id: 'using-filters',
+        }).items.map((x) => x.id)
+      : []
 
-  const modifierIds = find(databaseFunctions, {
-    id: 'using-modifiers',
-  }).items.map((x) => x.id)
+  const modifierIds =
+    databaseFunctions.length > 0
+      ? find(databaseFunctions, {
+          id: 'using-modifiers',
+        }) &&
+        find(databaseFunctions, {
+          id: 'using-modifiers',
+        }).items.map((x) => x.id)
+      : []
 
-  // return (
-  //   <>
-  //     <h1>something</h1>
-  //   </>
-  // )
+  // console.log(filterIds)
+  // console.log(modifierIds)
 
   return (
     <div
@@ -107,7 +128,6 @@ const NavigationMenuRefList = ({ currentLevel, setLevel, id, lib }) => {
       ].join(' ')}
     >
       <div className={'w-full flex flex-col gap-0 sticky top-8'}>
-        {/* {process.env.NEXT_PUBLIC_EXPERIMENTAL_REF !== 'true' && ( */}
         <Link href="/" passHref>
           <a
             className={[
@@ -123,8 +143,7 @@ const NavigationMenuRefList = ({ currentLevel, setLevel, id, lib }) => {
             <span>Back to Main Menu</span>
           </a>
         </Link>
-        {/* )} */}
-        {/* {process.env.NEXT_PUBLIC_EXPERIMENTAL_REF !== 'true' && ( */}
+
         <div className="flex items-center gap-3 my-3">
           <Image
             alt={id}
@@ -145,23 +164,15 @@ const NavigationMenuRefList = ({ currentLevel, setLevel, id, lib }) => {
         {/* )} */}
 
         <ul className="function-link-list">
-          {/* {introItems.map((item) => (
-            // @ts-ignore
-            <FunctionLink library={menu.title} {...item} />
-          ))} */}
-
-          {allCurrentFunctions.map((fn: any) => {
-            // const toplevelItems = fn.items.filter((item) => !item.parent)
-            // toplevelItems.map((item) => <li>{item.title}</li>)
-
+          {sections.map((fn: any) => {
             const RenderLink = (props) => {
               const activeAccordianItem = useMenuActiveRefId()
               let active = false
 
-              //console.log('render link id', props.id)
-
-              const isFilter = filterIds.includes(activeAccordianItem)
-              const isModifier = modifierIds.includes(activeAccordianItem)
+              const isFilter =
+                filterIds && filterIds.length > 0 && filterIds.includes(activeAccordianItem)
+              const isModifier =
+                modifierIds && modifierIds.length > 0 && modifierIds.includes(activeAccordianItem)
 
               if (
                 (isFilter && !isModifier && props.id === 'using-filters') ||
@@ -191,17 +202,15 @@ const NavigationMenuRefList = ({ currentLevel, setLevel, id, lib }) => {
                   value={active ? props.id : ''}
                 >
                   <Accordion.Item key={props.id + '-accordian-item'} value={props.id}>
-                    <FunctionLink {...props} library={props.library} />
+                    <FunctionLink {...props} library={lib} />
                     <Accordion.Content
                       key={props.id + '-sub-items-accordion-container'}
                       className="transition data-open:animate-slide-down data-closed:animate-slide-up ml-2"
                     >
                       {props.items &&
-                        props.items
-                          .filter((item) => item.libs.includes(lib))
-                          .map((item) => {
-                            return <FunctionLink {...item} library={menu.title} />
-                          })}
+                        props.items.map((item) => {
+                          return <FunctionLink {...item} library={lib} />
+                        })}
                     </Accordion.Content>
                   </Accordion.Item>
                 </Accordion.Root>
@@ -216,7 +225,7 @@ const NavigationMenuRefList = ({ currentLevel, setLevel, id, lib }) => {
                   <SideMenuTitle title={fn.title} />
                   {fn.items &&
                     fn.items
-                      .filter((item) => item.libs.includes(lib))
+                      // .filter((item) => item.libs.includes(lib))
                       .map((item) => <RenderLink {...item} library={menu.title} />)}
                 </>
               )
@@ -227,14 +236,14 @@ const NavigationMenuRefList = ({ currentLevel, setLevel, id, lib }) => {
                   <RenderLink {...fn} library={menu.title} />
                   {fn.items &&
                     fn.items
-                      .filter((item) => item.libs.includes(lib))
+                      // .filter((item) => item.libs.includes(lib))
                       .map((item) => <RenderLink {...item} library={menu.title} />)}
                 </>
               )
             }
           })}
         </ul>
-        {menu.extras && (
+        {/* {menu.extras && (
           <>
             <Divider />{' '}
             <span className="font-mono text-xs uppercase text-scale-1200 font-medium tracking-wider mb-2">
@@ -262,7 +271,7 @@ const NavigationMenuRefList = ({ currentLevel, setLevel, id, lib }) => {
               </li>
             </div>
           )
-        })}
+        })} */}
       </div>
     </div>
   )
diff --git a/apps/docs/components/Options.tsx b/apps/docs/components/Options.tsx
index 34f29821b07..f2d30c52f28 100644
--- a/apps/docs/components/Options.tsx
+++ b/apps/docs/components/Options.tsx
@@ -1,12 +1,11 @@
 import { FC, useState } from 'react'
 import { IconXCircle } from '~/../../packages/ui'
-import { AcceptedValue } from '~/pages/reference/cli/[...slug]'
 
 interface IOptions {
   name?: string
 }
 
-type IOption = AcceptedValue | any
+type IOption = any
 
 type OptionsSubComponents = {
   Option: IOption
diff --git a/apps/docs/components/Params.tsx b/apps/docs/components/Params.tsx
index 32118482069..ede7f8bcac7 100644
--- a/apps/docs/components/Params.tsx
+++ b/apps/docs/components/Params.tsx
@@ -1,11 +1,10 @@
 import { FC } from 'react'
-import { Flag } from '~/pages/reference/cli/[...slug]'
 
-type IParamProps = Flag | any
+type IParamProps = any
 
 const Param: FC<IParamProps> = (paramItem) => {
   return (
-    <div className="border-t border-b py-5 flex flex-col gap-3">
+    <li className="border-t border-b py-5 flex flex-col gap-3">
       <div className="flex gap-3 items-center">
         <span className="text-sm text-scale-1200 font-mono font-medium">
           {paramItem.name ?? 'no-name'}
@@ -23,7 +22,7 @@ const Param: FC<IParamProps> = (paramItem) => {
       </div>
       <p className="text-sm text-scale-1000 m-0">{paramItem.description ?? 'nodescription'}</p>
       {paramItem.children}
-    </div>
+    </li>
   )
 }
 
diff --git a/apps/docs/components/reference/ApiOperationSection.tsx b/apps/docs/components/reference/ApiOperationSection.tsx
new file mode 100644
index 00000000000..3db1698a2f7
--- /dev/null
+++ b/apps/docs/components/reference/ApiOperationSection.tsx
@@ -0,0 +1,113 @@
+import { Tabs } from '~/../../packages/ui'
+import CodeBlock from '~/components/CodeBlock/CodeBlock'
+import Param from '~/components/Params'
+import RefSubLayout from '~/layouts/ref/RefSubLayout'
+
+const ApiOperationSection = (props) => {
+  const operation = props.spec.operations.find((x: any) => x.operationId === props.funcData.id)
+
+  // gracefully return nothing if function does not exist
+  if (!operation) return <></>
+
+  return (
+    <RefSubLayout.Section
+      key={operation.operationId}
+      slug={operation.operationId}
+      title={operation.summary}
+      id={operation.operationId}
+      scrollSpyHeader={true}
+      monoFont={false}
+    >
+      <RefSubLayout.Details>
+        <div className="mt-4">
+          <code className="text-md flex gap-4 text-md text-scale-900 break-all">
+            <span
+              className="
+                uppercase 
+                whitespace-nowrap 
+                bg-scale-1200 text-scale-100 
+                flex items-center justify-center 
+                rounded-full font-mono font-medium text-xs px-2 py-0.5"
+            >
+              {operation.operation}
+            </span>
+            {operation.fullPath}
+          </code>
+        </div>
+        <div className="prose dark:prose-dark py-4">
+          <p>{operation.description}</p>
+        </div>
+        {/* Path Parameters */}
+        {operation.parameters &&
+          operation.parameters.filter((parameter) => parameter.in === 'path').length > 0 && (
+            <div className="not-prose mt-12">
+              <h5 className="mb-3 text-base text-scale-1200">Path Parameters</h5>
+              <ul className="mt-4">
+                {operation.parameters &&
+                  operation.parameters
+                    .filter((parameter: any) => parameter.in === 'path')
+                    .map((parameter: any) => (
+                      <Param {...parameter} isOptional={!parameter.required}></Param>
+                    ))}
+              </ul>
+            </div>
+          )}
+
+        {/* Query Parameters */}
+        {operation.parameters &&
+          operation.parameters.filter((parameter) => parameter.in === 'query').length > 0 && (
+            <div className="not-prose mt-12">
+              <h5 className="mb-3 text-base text-scale-1200">Query Parameters</h5>
+              <ul className="mt-4">
+                {operation.parameters &&
+                  operation.parameters
+                    .filter((parameter: any) => parameter.in === 'query')
+                    .map((parameter: any) => (
+                      <Param {...parameter} isOptional={!parameter.required}></Param>
+                    ))}
+              </ul>
+            </div>
+          )}
+
+        {/* Header Parameters */}
+        {operation.parameters &&
+          operation.parameters.filter((parameter) => parameter.in === 'header').length > 0 && (
+            <div className="not-prose mt-12">
+              <h5 className="mb-3 text-base text-scale-1200">Query Parameters</h5>
+              <ul className="mt-4">
+                {operation.parameters &&
+                  operation.parameters
+                    .filter((parameter: any) => parameter.in === 'header')
+                    .map((parameter: any) => (
+                      <Param {...parameter} isOptional={!parameter.required}></Param>
+                    ))}
+              </ul>
+            </div>
+          )}
+      </RefSubLayout.Details>
+      <RefSubLayout.Examples>
+        <h5 className="mb-3 text-base text-scale-1200">Responses</h5>
+        <Tabs
+          scrollable
+          size="small"
+          type="underlined"
+          defaultActiveId={operation.responseList[0].responseCode}
+        >
+          {operation.responseList.map((response: any) => (
+            <Tabs.Panel id={response.responseCode} label={response.responseCode}>
+              <p>{response.description}</p>
+              {response?.content && response?.content['application/json'] && (
+                <div className="mt-8">
+                  <CodeBlock language="bash" className="relative">
+                    {JSON.stringify(response.content['application/json'], null, 2)}
+                  </CodeBlock>
+                </div>
+              )}
+            </Tabs.Panel>
+          ))}
+        </Tabs>
+      </RefSubLayout.Examples>
+    </RefSubLayout.Section>
+  )
+}
+export default ApiOperationSection
diff --git a/apps/docs/components/reference/CLICommandSection.tsx b/apps/docs/components/reference/CLICommandSection.tsx
index 5fed86e034d..1e059c171a1 100644
--- a/apps/docs/components/reference/CLICommandSection.tsx
+++ b/apps/docs/components/reference/CLICommandSection.tsx
@@ -50,11 +50,12 @@ const CliCommandSection = (props) => {
 
   return (
     <RefSubLayout.Section
+      key={command.id}
       slug={command.id}
       title={'$ ' + command.title}
       id={command.id}
       monoFont={true}
-      scrollSpyHeader={false}
+      scrollSpyHeader={true}
     >
       <RefSubLayout.Details>
         <div className="grid ref-container" id={command.id}>
diff --git a/apps/docs/components/reference/RefSectionHandler.tsx b/apps/docs/components/reference/RefSectionHandler.tsx
index 17ceb8c34b4..89bd33ba1ec 100644
--- a/apps/docs/components/reference/RefSectionHandler.tsx
+++ b/apps/docs/components/reference/RefSectionHandler.tsx
@@ -7,6 +7,7 @@ import RefEducationSection from '~/components/reference/RefEducationSection'
 import RefFunctionSection from '~/components/reference/RefFunctionSection'
 import OldLayout from '~/layouts/Default'
 import RefSubLayout from '~/layouts/ref/RefSubLayout'
+import ApiOperationSection from './ApiOperationSection'
 import CliCommandSection from './CLICommandSection'
 
 interface Props {
@@ -58,6 +59,8 @@ const RefSectionHandler = (props) => {
           default:
             if (props.type === 'cli') {
               return <CliCommandSection funcData={x} commonFuncData={x} spec={props.spec} />
+            } else if (props.type === 'api') {
+              return <ApiOperationSection funcData={x} commonFuncData={x} spec={props.spec} />
             } else {
               return (
                 <RefFunctionSection
diff --git a/apps/docs/docs/ref/api/introduction.mdx b/apps/docs/docs/ref/api/introduction.mdx
new file mode 100644
index 00000000000..6f8c0bf427d
--- /dev/null
+++ b/apps/docs/docs/ref/api/introduction.mdx
@@ -0,0 +1,54 @@
+---
+id: introduction
+title: introduction
+hideTitle: true
+---
+
+<div className="flex items-start gap-6 not-prose mb-16">
+  <img src="/docs/img/icons/api-icon.svg" className="w-8 h-8 rounded" />
+  <div className="flex flex-col gap-2">
+    <h1 className="text-3xl text-scale-1200 m-0">Supabase API</h1>
+    <h2 className="text-base font-mono text-scale-1100">@supabase/supabase-js</h2>
+  </div>
+</div>
+
+<RefSubLayout.EducationRow>
+  <RefSubLayout.Details>
+
+      The Management API allows you to manage your projects programmatically.
+
+      ## Status
+
+      The Management API is in `beta`. It is usable in it's current state, but it's likely that there will be breaking changes.
+
+      ## Authentication
+
+      All API requests require a Supabase Personal token to be included in the Authorization header: `Authorization Bearer <supabase_personal_token`.
+      To generate or manage your API token, visit your [account](https://app.supabase.com/account/tokens) page.
+      Your API tokens carry the same privileges as your user account, so be sure to keep it secret.
+
+      ```bash
+        curl https://api.supabase.com/v1/projects \
+        -H "Authorization: Bearer sbp_bdd0••••••••••••••••••••••••••••••••4f23"
+      ```
+
+      All API requests must be authenticated and made over HTTPS.
+
+      ## Rate limits
+
+      The API is currently subject to our fair-use policy. In the future, are likely to introduce rate limits.
+      All resources created via the API are subject to the pricing detailed on our [Pricing](https://supabase.com/pricing) pages.
+
+    </RefSubLayout.Details>
+
+    <RefSubLayout.Examples>
+
+      Additional links
+
+      - [OpenAPI Docs](https://api.supabase.com/api/v1)
+      - [OpenAPI Spec](https://api.supabase.com/api/v1-json)
+      - Reporting bugs and issues: [github.com/supabase/supabase](https://github.com/supabase/supabase)
+
+      </RefSubLayout.Examples>
+
+  </RefSubLayout.EducationRow>
diff --git a/apps/docs/docs/ref/cli/introduction.mdx b/apps/docs/docs/ref/cli/introduction.mdx
index 31ed416a896..c928baba3d7 100644
--- a/apps/docs/docs/ref/cli/introduction.mdx
+++ b/apps/docs/docs/ref/cli/introduction.mdx
@@ -1,12 +1,17 @@
 ---
-id: intro
-slug: /
-sidebar_position: 1
-sidebar_label: Supabase CLI
-title: Supabase CLI
-hide_table_of_contents: true
+id: introduction
+title: introduction
+hideTitle: true
 ---
 
+<div className="flex items-start gap-6 not-prose mb-16">
+  <img src="/docs/img/icons/cli-icon.svg" className="w-8 h-8 rounded" />
+  <div className="flex flex-col gap-2">
+    <h1 className="text-3xl text-scale-1200 m-0">Supabase CLI</h1>
+    <h2 className="text-base font-mono text-scale-1100">@supabase/supabase-js</h2>
+  </div>
+</div>
+
 <RefSubLayout.EducationRow>
   <RefSubLayout.Details>
 
diff --git a/apps/docs/docs/ref/js/database.mdx b/apps/docs/docs/ref/javascript/database.mdx
similarity index 100%
rename from apps/docs/docs/ref/js/database.mdx
rename to apps/docs/docs/ref/javascript/database.mdx
diff --git a/apps/docs/docs/ref/js/installing.mdx b/apps/docs/docs/ref/javascript/installing.mdx
similarity index 100%
rename from apps/docs/docs/ref/js/installing.mdx
rename to apps/docs/docs/ref/javascript/installing.mdx
diff --git a/apps/docs/docs/ref/js/introduction.mdx b/apps/docs/docs/ref/javascript/introduction.mdx
similarity index 100%
rename from apps/docs/docs/ref/js/introduction.mdx
rename to apps/docs/docs/ref/javascript/introduction.mdx
diff --git a/apps/docs/docs/ref/js/release-notes.mdx b/apps/docs/docs/ref/javascript/release-notes.mdx
similarity index 100%
rename from apps/docs/docs/ref/js/release-notes.mdx
rename to apps/docs/docs/ref/javascript/release-notes.mdx
diff --git a/apps/docs/docs/ref/js/typescript-support.mdx b/apps/docs/docs/ref/javascript/typescript-support.mdx
similarity index 100%
rename from apps/docs/docs/ref/js/typescript-support.mdx
rename to apps/docs/docs/ref/javascript/typescript-support.mdx
diff --git a/apps/docs/docs/ref/js/v1/introduction.mdx b/apps/docs/docs/ref/javascript/v1/introduction.mdx
similarity index 100%
rename from apps/docs/docs/ref/js/v1/introduction.mdx
rename to apps/docs/docs/ref/javascript/v1/introduction.mdx
diff --git a/apps/docs/docs/ref/js/v1/release-notes.mdx b/apps/docs/docs/ref/javascript/v1/release-notes.mdx
similarity index 100%
rename from apps/docs/docs/ref/js/v1/release-notes.mdx
rename to apps/docs/docs/ref/javascript/v1/release-notes.mdx
diff --git a/apps/docs/layouts/ref/RefSubLayout.tsx b/apps/docs/layouts/ref/RefSubLayout.tsx
index 2a216fed366..b65c01aac28 100644
--- a/apps/docs/layouts/ref/RefSubLayout.tsx
+++ b/apps/docs/layouts/ref/RefSubLayout.tsx
@@ -54,9 +54,10 @@ const Section: FC<ISectionContainer> = (props) => {
   return (
     <article
       key={props.id}
-      className={`${
-        props.singleColumn ? 'prose dark:prose-dark py-16 lg:py-32 w-full' : 'py-16 lg:py-32 w-full'
-      }`}
+      className={[
+        props.singleColumn ? 'prose dark:prose-dark w-full' : 'w-full',
+        'py-16 lg:py-32 first:pt-8 last:pb-8',
+      ].join(' ')}
     >
       <StickyHeader {...props} />
       <div
@@ -124,7 +125,10 @@ const EducationRow: FC<IEducationRow> = (props) => {
 const EducationSection: FC<IEducationSection> = ({ hideTitle = false, ...props }) => {
   // console.log({ props })
   return (
-    <article key={props.id} className={`${'prose dark:prose-dark max-w-none py-16 lg:py-32'}`}>
+    <article
+      key={props.id}
+      className={'prose dark:prose-dark max-w-none py-16 lg:py-32 first:pt-8 last:pb-8'}
+    >
       {!hideTitle && <StickyHeader {...props} />}
       {props.children}
     </article>
diff --git a/apps/docs/pages/reference/api/[...slug].tsx b/apps/docs/pages/reference/api/[...slug].tsx
index 8befd6526f6..eb1400d4439 100644
--- a/apps/docs/pages/reference/api/[...slug].tsx
+++ b/apps/docs/pages/reference/api/[...slug].tsx
@@ -1,294 +1,26 @@
-import fs from 'fs'
-import matter from 'gray-matter'
-import { getAllDocs, getDocsBySlug } from '~/lib/docs'
+import apiCommonSections from '~/../../spec/common-api-sections.json' assert { type: 'json' }
 import specFile from '~/../../spec/transforms/api_v0_openapi_deparsed.json' assert { type: 'json' }
-import { gen_v3, enrichedOperation } from '~/lib/refGenerator/helpers'
-import { Tabs } from '~/../../packages/ui'
-import components from '~/components/index'
-import { MDXRemote } from 'next-mdx-remote'
-import { serialize } from 'next-mdx-remote/serialize'
-import toc from 'markdown-toc'
+import RefSectionHandler from '~/components/reference/RefSectionHandler'
+import { flattenSections } from '~/lib/helpers'
+import handleRefGetStaticPaths from '~/lib/mdx/handleRefStaticPaths'
+import handleRefStaticProps from '~/lib/mdx/handleRefStaticProps'
+import { gen_v3 } from '~/lib/refGenerator/helpers'
 
-// @ts-ignore
-import CodeBlock from '~/components/CodeBlock/CodeBlock'
-import RefSubLayout from '~/layouts/ref/RefSubLayout'
-
-export type AcceptedValue = {
-  id: string
-  name: string
-  type: 'string' | 'boolean' | 'object'
-  description?: string
-}
-
-export type Flag = {
-  id: string
-  name: string
-  description: string
-  default_value: string
-  accepted_values: AcceptedValue[]
-}
-
-export type ApiParameter = {
-  example: string
-  in: string
-  name: string
-  required: boolean
-  schema: {
-    type: string
-    example: string
-  }
-}
 // @ts-ignore
 const generatedSpec = gen_v3(specFile, 'wat', { apiUrl: 'apiv0' })
 
-//console.log({ generatedSpec })
+const sections = flattenSections(apiCommonSections)
+
+console.log('sections', sections)
+
 export default function Config(props) {
-  return (
-    <>
-      <RefSubLayout>
-        {props.docs
-          .filter((doc) => doc.introPage)
-          .map((item) => (
-            <RefSubLayout.Section
-              key={item.id}
-              title={item.meta.title}
-              id={item.id}
-              slug={item.id}
-              scrollSpyHeader={true}
-              singleColumn={true}
-            >
-              <MDXRemote {...item.content} components={components} />
-            </RefSubLayout.Section>
-          ))}
-      </RefSubLayout>
-      <hr />
-      <RefSubLayout>
-        <div className="flex">
-          <div className="w-full">
-            <div className="grid gap-16">
-              <h1 className="text-4xl">{generatedSpec.info.title}</h1>
-              <p>{generatedSpec.info.description}</p>
-            </div>
-
-            <div className="grid gap-32 mx-auto max-w-5xl mt-24">
-              {generatedSpec.sections.map((section) => (
-                <>
-                  <h2 className="text-3xl">{section.title}</h2>
-                  {section.operations.map((operation: any) => (
-                    <div className="border-b pb-8">
-                      <RefSubLayout.Section
-                        slug={operation.id}
-                        title={operation.summary}
-                        id={operation.operationId}
-                        monoFont={false}
-                      >
-                        <RefSubLayout.Details>
-                          <div className="mt-4">
-                            <code className="text-md flex gap-4 text-md text-scale-900 break-all">
-                              <span className="uppercase whitespace-nowrap	">
-                                {operation.operation}
-                              </span>
-                              {operation.fullPath}
-                            </code>
-                          </div>
-                          {/* Path Parameters */}
-                          {operation.parameters &&
-                            operation.parameters.filter((parameter) => parameter.in === 'path')
-                              .length > 0 && (
-                              <div className="mt-12">
-                                <h2 className="border-b pb-2 text-xl">Path parameters</h2>
-                                <ul className="mt-4">
-                                  {operation.parameters &&
-                                    operation.parameters
-                                      .filter((parameter: any) => parameter.in === 'path')
-                                      .map((parameter: any) => (
-                                        <li className="mt-8 border-b pb-6">
-                                          <div>
-                                            <div className="flex gap-4 items-center">
-                                              <span className="font-bold">{parameter.name}</span>
-                                              <div className="font-mono text-xs break-all">
-                                                {parameter.required && (
-                                                  <div className="text-[10px] border border-amber-700 bg-amber-300 text-amber-900 px-2 tracking-wide font-mono py-0.25 rounded-full">
-                                                    REQUIRED
-                                                  </div>
-                                                )}
-                                              </div>
-                                            </div>
-                                            <p className="mt-4">{parameter.description}</p>
-                                          </div>
-                                          {parameter.example && (
-                                            <div className="mt-4 flex gap-4 items-center">
-                                              <span>Example:</span>
-                                              <span className="font-mono text-xs break-all">
-                                                {parameter.example}
-                                              </span>
-                                            </div>
-                                          )}
-                                        </li>
-                                      ))}
-                                </ul>
-                              </div>
-                            )}
-
-                          {/* Header Parameters */}
-                          {operation.parameters &&
-                            operation.parameters.filter((parameter) => parameter.in === 'header')
-                              .length > 0 && (
-                              <div className="mt-12">
-                                <h2 className="border-b pb-2 text-xl">Header parameters</h2>
-                                <ul className="mt-4">
-                                  {operation.parameters &&
-                                    operation.parameters
-                                      .filter((parameter: any) => parameter.in === 'header')
-                                      .map((parameter: any) => (
-                                        <li className="mt-8 border-b pb-6">
-                                          <div className="flex gap-4 items-center">
-                                            <span className="font-bold">{parameter.name}</span>
-                                            <span className="font-mono text-xs break-all">
-                                              {parameter.required && 'required'}
-                                            </span>
-                                          </div>
-                                          <div className="mt-4 flex gap-4 items-center">
-                                            <span>Example:</span>
-                                            <span className="font-mono text-xs break-all">
-                                              {parameter.example}
-                                            </span>
-                                          </div>
-                                        </li>
-                                      ))}
-                                </ul>
-                              </div>
-                            )}
-                        </RefSubLayout.Details>
-                        <RefSubLayout.Examples>
-                          <h2 className="text-xl">Responses</h2>
-                          <Tabs
-                            scrollable
-                            size="small"
-                            type="underlined"
-                            defaultActiveId={operation.responseList[0].responseCode}
-                          >
-                            {operation.responseList.map((response: any) => (
-                              <Tabs.Panel id={response.responseCode} label={response.responseCode}>
-                                <p>{response.description}</p>
-                                {response?.content && response?.content['application/json'] && (
-                                  <div className="mt-8">
-                                    <CodeBlock language="bash" className="relative">
-                                      {JSON.stringify(
-                                        response.content['application/json'],
-                                        null,
-                                        2
-                                      )}
-                                    </CodeBlock>
-                                  </div>
-                                )}
-                              </Tabs.Panel>
-                            ))}
-                          </Tabs>
-                        </RefSubLayout.Examples>
-                      </RefSubLayout.Section>
-                    </div>
-                  ))}
-                </>
-              ))}
-            </div>
-          </div>
-        </div>
-      </RefSubLayout>
-    </>
-  )
+  return <RefSectionHandler sections={sections} spec={generatedSpec} pageProps={props} type="api" />
 }
 
 export async function getStaticProps({ params }: { params: { slug: string[] } }) {
-  // an array of ids of the intro sections for this library
-  const introPages = ['api']
-  const specPpages = generatedSpec.sections
-
-  const pages = [...introPages, ...specPpages]
-
-  /**
-   * Read all the markdown files that might have
-   *  - custom text
-   *  - call outs
-   *  - important notes regarding implementation
-   */
-  const allMarkdownDocs = await Promise.all(
-    pages.map(async (x: any, i) => {
-      const pathName = `docs/ref/api/${x}.mdx`
-
-      function checkFileExists(x) {
-        // console.log('checking this ', x)
-        if (fs.existsSync(x)) {
-          return true
-        } else {
-          return false
-        }
-      }
-
-      const markdownExists = checkFileExists(pathName)
-
-      const fileContents = markdownExists ? fs.readFileSync(pathName, 'utf8') : ''
-      const { data, content } = matter(fileContents)
-
-      return {
-        id: x,
-        title: x,
-        // ...content,
-        meta: data,
-        introPage: introPages.includes(x),
-        content: content ? await serialize(content || '') : null,
-      }
-    })
-  )
-
-  /*
-   * old content generation
-   * this is for grabbing to old markdown files
-   */
-
-  let slug
-  if (params.slug.length > 1) {
-    slug = `docs/reference/cli/${params.slug.join('/')}`
-  } else {
-    slug = `docs/reference/cli/${params.slug[0]}`
-  }
-
-  /*
-   * handle old ref pages
-   */
-  if (process.env.NEXT_PUBLIC_NEW_DOCS === 'false') {
-    let doc = getDocsBySlug(slug)
-    const content = await serialize(doc.content || '')
-    return {
-      props: {
-        /*
-         * old reference docs are below
-         */
-        ...doc,
-        content,
-        toc: toc(doc.content, { maxdepth: 1, firsth1: false }),
-      },
-    }
-  } else {
-    return {
-      props: {
-        docs: allMarkdownDocs,
-      },
-    }
-  }
+  return handleRefStaticProps(sections, params, '/api', '/api')
 }
 
 export function getStaticPaths() {
-  let docs = getAllDocs()
-
-  return {
-    paths: docs.map(() => {
-      return {
-        params: {
-          slug: docs.map((d) => d.slug),
-        },
-      }
-    }),
-    fallback: 'blocking',
-  }
+  return handleRefGetStaticPaths()
 }
diff --git a/apps/docs/pages/reference/cli/[...slug].tsx b/apps/docs/pages/reference/cli/[...slug].tsx
index 713edef83b1..8da57ec4930 100644
--- a/apps/docs/pages/reference/cli/[...slug].tsx
+++ b/apps/docs/pages/reference/cli/[...slug].tsx
@@ -1,9 +1,6 @@
 // @ts-expect-error
 import spec from '~/../../spec/cli_v1_commands_new_shape.yaml' assert { type: 'yml' }
 
-import { MDXRemote } from 'next-mdx-remote'
-import components from '~/components/index'
-import OldLayout from '~/layouts/Default'
 import { flattenSections } from '~/lib/helpers'
 
 import cliCommonSections from '~/../../spec/common-cli-sections.json' assert { type: 'json' }
@@ -13,59 +10,7 @@ import handleRefStaticProps from '~/lib/mdx/handleRefStaticProps'
 
 const sections = flattenSections(cliCommonSections)
 
-export type AcceptedValue = {
-  id: string
-  name: string
-  type: 'string' | 'boolean' | 'object'
-  description?: string
-}
-
-export type Flag = {
-  id: string
-  name: string
-  description: string
-  default_value: string
-  accepted_values: AcceptedValue[]
-}
-
-export type Command = {
-  id: string
-  title: string
-  description: string
-  flags?: Flag[]
-  summary: string
-  tags?: []
-  links?: []
-  subcommands?: []
-  usage?: string
-}
-
-export default function Config(props) {
-  console.log(props.docs)
-
-  console.log(
-    spec.commands.map((x) => {
-      return {
-        id: x.id,
-        title: x.title,
-        slug: x.id,
-        isFunc: true,
-      }
-    })
-  )
-
-  /*
-   * handle old ref pages
-   */
-  if (process.env.NEXT_PUBLIC_NEW_DOCS === 'false') {
-    return (
-      // @ts-ignore
-      <OldLayout meta={props.meta} toc={props.toc}>
-        <MDXRemote {...props.content} components={components} />
-      </OldLayout>
-    )
-  }
-
+export default function CliRef(props) {
   return <RefSectionHandler sections={sections} spec={spec} pageProps={props} type="cli" />
 }
 
diff --git a/apps/docs/pages/reference/javascript/[...slug].tsx b/apps/docs/pages/reference/javascript/[...slug].tsx
index d77ac59043d..861f9a753d6 100644
--- a/apps/docs/pages/reference/javascript/[...slug].tsx
+++ b/apps/docs/pages/reference/javascript/[...slug].tsx
@@ -14,7 +14,7 @@ export default function JSReference(props) {
 }
 
 export async function getStaticProps({ params }: { params: { slug: string[] } }) {
-  return handleRefStaticProps(sections, params, '/js', '/javascript')
+  return handleRefStaticProps(sections, params, '/javascript', '/javascript')
 }
 
 export function getStaticPaths() {
diff --git a/apps/docs/pages/reference/javascript/v1/[...slug].tsx b/apps/docs/pages/reference/javascript/v1/[...slug].tsx
index a7ab77170b6..277a0c71f79 100644
--- a/apps/docs/pages/reference/javascript/v1/[...slug].tsx
+++ b/apps/docs/pages/reference/javascript/v1/[...slug].tsx
@@ -14,7 +14,7 @@ export default function JSReference(props) {
 }
 
 export async function getStaticProps({ params }: { params: { slug: string[] } }) {
-  return handleRefStaticProps(sections, params, '/js/v1', '/javascript/v1')
+  return handleRefStaticProps(sections, params, '/javascript/v1', '/javascript/v1')
 }
 
 export function getStaticPaths() {
diff --git a/spec/common-api-sections.json b/spec/common-api-sections.json
new file mode 100644
index 00000000000..cd0eaaff407
--- /dev/null
+++ b/spec/common-api-sections.json
@@ -0,0 +1,194 @@
+[
+  {
+    "title": "Introduction",
+    "id": "introduction",
+    "slug": "introduction",
+    "isFunc": false
+  },
+  {
+    "title": "Projects",
+    "items": [
+      {
+        "id": "list-all-projects",
+        "title": "List all projects",
+        "slug": "list-all-projects",
+        "isFunc": true
+      },
+      {
+        "id": "create-a-project",
+        "title": "Create a project",
+        "slug": "create-a-project",
+        "isFunc": true
+      },
+      {
+        "id": "list-all-organizations",
+        "title": "List all organizations",
+        "slug": "list-all-organizations",
+        "isFunc": true
+      },
+      {
+        "id": "create-an-organization",
+        "title": "Create an organization",
+        "slug": "create-an-organization",
+        "isFunc": true
+      }
+    ]
+  },
+  {
+    "title": "Secrets",
+    "items": [
+      {
+        "id": "list-all-secrets",
+        "title": "List all secrets",
+        "slug": "list-all-secrets",
+        "isFunc": true
+      },
+      {
+        "id": "bulk-create-secrets",
+        "title": "Bulk create secrets",
+        "slug": "bulk-create-secrets",
+        "isFunc": true
+      },
+      {
+        "id": "bulk-delete-secrets",
+        "title": "Bulk delete secrets",
+        "slug": "bulk-delete-secrets",
+        "isFunc": true
+      }
+    ]
+  },
+  {
+    "title": "Typescript",
+    "items": [
+      {
+        "id": "generate-typescript-types",
+        "title": "Generate TypeScript types",
+        "slug": "generate-typescript-types",
+        "isFunc": true
+      }
+    ]
+  },
+  {
+    "title": "Functions",
+    "items": [
+      {
+        "id": "create-a-function",
+        "title": "Create a function",
+        "slug": "create-a-function",
+        "isFunc": true
+      },
+      {
+        "id": "list-all-functions",
+        "title": "List all functions",
+        "slug": "list-all-functions",
+        "isFunc": true
+      },
+      {
+        "id": "retrieve-a-function",
+        "title": "Retrieve a function",
+        "slug": "retrieve-a-function",
+        "isFunc": true
+      },
+      {
+        "id": "update-a-function",
+        "title": "Update a function",
+        "slug": "update-a-function",
+        "isFunc": true
+      },
+      {
+        "id": "delete-a-function",
+        "title": "Delete a function",
+        "slug": "delete-a-function",
+        "isFunc": true
+      },
+      {
+        "id": "retrieve-a-function-body",
+        "title": "Retrieve a function body",
+        "slug": "retrieve-a-function-body",
+        "isFunc": true
+      }
+    ]
+  },
+
+  {
+    "title": "Hostname",
+    "items": [
+      {
+        "id": "gets-projects-custom-hostname-config",
+        "title": "Gets project's custom hostname config",
+        "slug": "gets-projects-custom-hostname-config",
+        "isFunc": true
+      },
+      {
+        "id": "deletes-a-projects-custom-hostname-configuration",
+        "title": "Deletes a project's custom hostname configuration",
+        "slug": "deletes-a-projects-custom-hostname-configuration",
+        "isFunc": true
+      },
+      {
+        "id": "updates-projects-custom-hostname-configuration",
+        "title": "Updates project's custom hostname configuration",
+        "slug": "updates-projects-custom-hostname-configuration",
+        "isFunc": true
+      },
+      {
+        "id": "attempts-to-verify-the-dns-configuration-for-projects-custom-hostname-configuration",
+        "title": "Attempts to verify the DNS configuration for project's custom hostname configuration",
+        "slug": "attempts-to-verify-the-dns-configuration-for-projects-custom-hostname-configuration",
+        "isFunc": true
+      },
+      {
+        "id": "activates-a-custom-hostname-for-a-project",
+        "title": "Activates a custom hostname for a project.",
+        "slug": "activates-a-custom-hostname-for-a-project",
+        "isFunc": true
+      }
+    ]
+  },
+  {
+    "title": "pgsodium",
+    "items": [
+      {
+        "id": "gets-projects-pgsodium-config",
+        "title": "Gets project's pgsodium config",
+        "slug": "gets-projects-pgsodium-config",
+        "isFunc": true
+      },
+      {
+        "id": "updates-projects-pgsodium-config-updating-the-root_key-can-cause-all-data-encrypted-with-the-older-key-to-become-inaccessible",
+        "title": "Updates project's pgsodium config. Updating the root_key can cause all data encrypted with the older key to become inaccessible.",
+        "slug": "updates-projects-pgsodium-config-updating-the-root_key-can-cause-all-data-encrypted-with-the-older-key-to-become-inaccessible",
+        "isFunc": true
+      }
+    ]
+  },
+  {
+    "title": "Network",
+    "items": [
+      {
+        "id": "gets-projects-network-bans",
+        "title": "Gets project's network bans",
+        "slug": "gets-projects-network-bans",
+        "isFunc": true
+      },
+      {
+        "id": "remove-network-bans",
+        "title": "Remove network bans.",
+        "slug": "remove-network-bans",
+        "isFunc": true
+      },
+      {
+        "id": "gets-projects-network-restrictions",
+        "title": "Gets project's network restrictions",
+        "slug": "gets-projects-network-restrictions",
+        "isFunc": true
+      },
+      {
+        "id": "updates-projects-network-restrictions",
+        "title": "Updates project's network restrictions",
+        "slug": "updates-projects-network-restrictions",
+        "isFunc": true
+      }
+    ]
+  }
+]
diff --git a/spec/common-cli-sections.json b/spec/common-cli-sections.json
index 73698c45b5e..398acf409f6 100644
--- a/spec/common-cli-sections.json
+++ b/spec/common-cli-sections.json
@@ -1,6 +1,6 @@
 [
   {
-    "title": "introduction",
+    "title": "Introduction",
     "id": "introduction",
     "slug": "introduction",
     "isFunc": false