;
+
+ try {
+ const res = await fetch(SPEC_URL, { next: { revalidate: 300 } });
+ if (!res.ok) throw new Error(`Spec fetch failed: ${res.status}`);
+ spec = await res.json();
+ } catch {
+ return Failed to load API spec. Please try again later.
;
+ }
+
+ // --- info-block cleanup ---
+
+ if (spec.info && typeof spec.info === 'object') {
+ const info = spec.info as Record;
+ delete info.contact;
+ delete info.license;
+ if (typeof info.description === 'string') {
+ info.description = info.description.replaceAll(
+ 'https://neon.tech/docs/',
+ 'https://neon.com/docs/'
+ );
+ }
+ }
+
+ // --- inject TAG_INTROS as descriptions on existing tags ---
+ // Scalar renders tag descriptions as a content block above the tag's
+ // operations, so this adds a rich intro without an extra sidebar entry.
+
+ if (Array.isArray(spec.tags)) {
+ const tags = spec.tags as Array<{ name: string; description?: string }>;
+ await Promise.all(
+ Object.entries(TAG_INTROS).map(async ([tagName, file]) => {
+ const content = await readGuide(file);
+ if (!content) return;
+ const tag = tags.find((t) => t.name === tagName);
+ if (tag) tag.description = content;
+ })
+ );
+ }
+
+ // --- inject SIDEBAR_GUIDES as synthetic tags so they appear in the sidebar ---
+ // Tags with no operations but a description are rendered as pages by Scalar
+ // (PR #7414, Nov 2025). "Introduction" is already auto-generated from
+ // info.description — don't duplicate it here.
+
+ const guideTags = (
+ await Promise.all(
+ SIDEBAR_GUIDES.map(async ({ tagName, file }) => {
+ const content = await readGuide(file);
+ return content ? { name: tagName, description: content } : null;
+ })
+ )
+ ).filter((t): t is { name: string; description: string } => t !== null);
+
+ if (guideTags.length > 0) {
+ const existingTags = Array.isArray(spec.tags) ? (spec.tags as Array<{ name: string }>) : [];
+ spec.tags = [...guideTags, ...existingTags];
+
+ // Collect tags actually used by at least one operation so we can drop
+ // empty-but-declared tags from the sidebar (e.g. "Preview" is defined in
+ // the spec but currently has no operations, rendering as a blank page).
+ const usedTagNames = new Set();
+ if (spec.paths && typeof spec.paths === 'object') {
+ for (const pathItem of Object.values(spec.paths as Record)) {
+ if (!pathItem || typeof pathItem !== 'object') continue;
+ for (const op of Object.values(pathItem as Record)) {
+ if (!op || typeof op !== 'object') continue;
+ const opTags = (op as { tags?: unknown }).tags;
+ if (!Array.isArray(opTags)) continue;
+ for (const t of opTags) {
+ if (typeof t === 'string') usedTagNames.add(t);
+ }
+ }
+ }
+ }
+
+ // x-tagGroups must list every tag explicitly — anything not listed is
+ // hidden by Scalar. The "Guides" group pins our pages above the
+ // alphabetically-sorted API tags.
+ spec['x-tagGroups'] = [
+ { name: 'Guides', tags: guideTags.map((t) => t.name) },
+ {
+ name: 'API Reference',
+ tags: existingTags.map((t) => t.name).filter((n) => usedTagNames.has(n)),
+ },
+ ];
+ }
+
+ return ;
+}
diff --git a/src/app/(api-docs)/layout.tsx b/src/app/(api-docs)/layout.tsx
new file mode 100644
index 0000000000..f396343d2e
--- /dev/null
+++ b/src/app/(api-docs)/layout.tsx
@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import Layout from 'components/shared/layout';
+import { DOCS_BASE_PATH } from 'constants/docs';
+import { getNavigation } from 'utils/api-docs';
+
+export default async function ApiDocsLayout({ children }: { children: ReactNode }) {
+ const navigation = await getNavigation();
+
+ return (
+
+ {children}
+
+ );
+}
diff --git a/src/content/api-docs/auth-intro.md b/src/content/api-docs/auth-intro.md
new file mode 100644
index 0000000000..db19e683d3
--- /dev/null
+++ b/src/content/api-docs/auth-intro.md
@@ -0,0 +1,16 @@
+Neon Auth lets you add user authentication to your application backed by your Neon Postgres database. The endpoints below let you manage Neon Auth projects programmatically — provisioning auth for a Neon project, rotating keys, and inspecting state.
+
+## When to use this API
+
+Use the Neon Auth API when you need to automate auth setup as part of your deployment pipeline or internal tooling. If you're integrating authentication into an application, you'll typically use the [@neondatabase/auth](https://neon.com/docs/neon-auth) SDK instead, which talks to the service directly.
+
+## Prerequisites
+
+- A Neon project with the Auth feature enabled on your plan.
+- An API key with permission to manage the target project. See [Manage API keys](https://neon.com/docs/manage/api-keys) for how to create one.
+
+All requests require a bearer token in the `Authorization` header:
+
+```bash
+Authorization: Bearer $NEON_API_KEY
+```
diff --git a/src/content/api-docs/branch-intro.md b/src/content/api-docs/branch-intro.md
new file mode 100644
index 0000000000..17d8ebbb23
--- /dev/null
+++ b/src/content/api-docs/branch-intro.md
@@ -0,0 +1,18 @@
+Neon branches are copy-on-write clones of your database, created from any point in time. A new branch shares storage with its parent until it diverges, so creating one is cheap and fast.
+
+Common uses:
+
+- Development and preview environments per pull request or per developer
+- Testing schema changes before promoting them
+- Point-in-time recovery by branching from a past timestamp
+
+## When to use this API
+
+Use these endpoints to create, list, or delete branches from CI/CD and platform automation. For interactive work, the [Neon Console](https://console.neon.tech) and [Neon CLI](https://neon.com/docs/reference/cli-branches) cover the same operations.
+
+## Key constraints
+
+- You cannot delete a project's root branch.
+- You cannot delete a branch that has child branches. Delete or reparent the children first.
+
+See the [Branching with the Neon API guide](https://neon.com/docs/guides/branching-neon-api) for end-to-end examples.
diff --git a/src/content/api-docs/consumption-intro.md b/src/content/api-docs/consumption-intro.md
new file mode 100644
index 0000000000..0d47a36f6d
--- /dev/null
+++ b/src/content/api-docs/consumption-intro.md
@@ -0,0 +1,17 @@
+The Consumption API returns usage metrics (compute, storage, data transfer) for monitoring, reporting, and custom billing dashboards.
+
+## Scope
+
+Metrics are available at three levels:
+
+- **Account**: usage across all projects you own.
+- **Organization**: usage across an organization's projects. See [Organization consumption](https://neon.com/docs/manage/orgs-api-consumption).
+- **Project**: per-project metrics on usage-based plans.
+
+> [!NOTE]
+> A separate set of legacy consumption endpoints exists for historical integrations. New code should use the current endpoints. See [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics) for which to use and when.
+
+## Related guides
+
+- [Cost optimization](https://neon.com/docs/introduction/cost-optimization). Strategies for keeping compute, storage, and data transfer costs down.
+- [Reduce network transfer costs](https://neon.com/docs/introduction/network-transfer). How data transfer is metered and how to lower it.
diff --git a/src/content/api-docs/endpoint-intro.md b/src/content/api-docs/endpoint-intro.md
new file mode 100644
index 0000000000..72d9fcdbf9
--- /dev/null
+++ b/src/content/api-docs/endpoint-intro.md
@@ -0,0 +1,12 @@
+> [!NOTE]
+> In Neon, a **compute endpoint** is the Postgres compute instance attached to a [branch](#tag/branch), not an HTTP endpoint. Your applications connect to it over the standard Postgres protocol.
+
+A compute endpoint runs your Postgres workload. Each branch has one `read_write` endpoint and can have any number of `read_only` endpoints (used for read replicas and analytics).
+
+Computes [scale to zero](https://neon.com/docs/guides/scale-to-zero-guide) after 5 minutes of inactivity by default, and wake automatically on the next connection. You can tune the timeout via `suspend_timeout_seconds`.
+
+## When to use this API
+
+Use these endpoints to create, configure, restart, or delete computes. Typical cases: adding read replicas, tuning compute size, or changing scale-to-zero behavior. The [Neon Console](https://console.neon.tech) and [Neon CLI](https://neon.com/docs/reference/neon-cli) cover the same operations for interactive work.
+
+See [Manage compute endpoints](https://neon.com/docs/manage/computes) for configuration details and [Read replicas](https://neon.com/docs/introduction/read-replicas) for the read-only variant.
diff --git a/src/content/api-docs/getting-started.md b/src/content/api-docs/getting-started.md
new file mode 100644
index 0000000000..036ae0af81
--- /dev/null
+++ b/src/content/api-docs/getting-started.md
@@ -0,0 +1,106 @@
+Make your first Neon API request in under two minutes.
+
+## 1. Get an API key
+
+Open the [Neon Console](https://console.neon.tech), go to **Account settings > API keys**, and create a key.
+
+> [!WARNING]
+> Neon shows the key once. Copy it now; you cannot retrieve it later.
+
+Neon supports three key scopes. Pick the narrowest one that fits:
+
+| Scope | Access | Best for |
+| --- | --- | --- |
+| Personal | All projects you own or have access to | Personal scripts and development |
+| Organization | All projects in an organization | Team automation and CI/CD |
+| Project-scoped | A single project | Limited-access integrations |
+
+See [Manage API keys](https://neon.com/docs/manage/api-keys) for the full rules.
+
+```bash
+export NEON_API_KEY="neon_api_..."
+```
+
+## 2. Authenticate
+
+Send your key as a Bearer token in the `Authorization` header on every request:
+
+```
+Authorization: Bearer
+```
+
+## 3. Make your first request
+
+List the projects on your account to confirm the key works:
+
+```bash
+curl https://console.neon.tech/api/v2/projects \
+ --header "Authorization: Bearer $NEON_API_KEY"
+```
+
+The response lists your projects:
+
+```json
+{
+ "projects": [
+ {
+ "id": "spring-example-302709",
+ "name": "my-project",
+ "region_id": "aws-us-east-2",
+ "created_at": "2024-01-15T10:30:00Z"
+ }
+ ]
+}
+```
+
+Use a `project_id` from the response in any follow-up request.
+
+## Rate limits
+
+Neon enforces:
+
+- 700 requests per minute across your account
+- 40 requests per second burst per route
+- 10 requests per second on `POST /organizations/{org_id}/api_keys`
+
+Exceeding a limit returns `429 Too Many Requests`. Retry with exponential backoff.
+
+## Pagination
+
+List endpoints support cursor pagination via `limit` and `cursor`:
+
+```bash
+# First page
+curl 'https://console.neon.tech/api/v2/projects?limit=10' \
+ --header "Authorization: Bearer $NEON_API_KEY"
+
+# Next page: pass the cursor from the previous response
+curl 'https://console.neon.tech/api/v2/projects?limit=10&cursor=...' \
+ --header "Authorization: Bearer $NEON_API_KEY"
+```
+
+## Asynchronous operations
+
+Many endpoints (create branch, start compute, restore snapshot) return immediately while work continues in the background. The response includes an `operations` array:
+
+```json
+"operations": [
+ {
+ "id": "22acbb37-209b-4b90-a39c-8460090e1329",
+ "action": "create_branch",
+ "status": "running"
+ }
+]
+```
+
+Status values: `scheduling`, `running`, `finished`, `failed`, `cancelling`, `cancelled`, `skipped`.
+
+Poll the [Operation](#tag/operation) endpoint until `status` is `finished` before issuing follow-up requests that depend on the result.
+
+## SDKs and tools
+
+- [TypeScript SDK](https://neon.com/docs/reference/typescript-sdk). Typed Node.js and browser client.
+- [Python SDK](https://neon.com/docs/reference/python-sdk). Pythonic wrapper for the Neon API.
+- [@neondatabase/toolkit](https://neon.com/docs/reference/neondatabase-toolkit). API client plus serverless driver, tuned for AI agents.
+- [Neon CLI](https://neon.com/docs/reference/neon-cli). Terminal access to the same API.
+- [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server). Natural-language control of the Neon API from AI assistants like Cursor and Claude.
diff --git a/src/content/api-docs/operation-intro.md b/src/content/api-docs/operation-intro.md
new file mode 100644
index 0000000000..418c0065e0
--- /dev/null
+++ b/src/content/api-docs/operation-intro.md
@@ -0,0 +1,12 @@
+Operations represent background jobs Neon runs to fulfill your API requests: creating branches, starting computes, restoring snapshots, and similar work. Each operation has an ID and a status you can poll.
+
+Status values: `scheduling`, `running`, `finished`, `failed`, `cancelling`, `cancelled`, `skipped`.
+
+See [Getting Started](#tag/getting-started) for the polling pattern and an example response.
+
+## Key constraints
+
+- Neon limits overlapping operations on a single project. Requests that conflict with a running operation return `423 Locked`. Retry with exponential backoff, or wait for the in-flight operation to finish.
+- Operations older than 6 months may be pruned from Neon's systems.
+
+See [Operations](https://neon.com/docs/manage/operations) for details and handling guidance.
diff --git a/src/content/api-docs/project-intro.md b/src/content/api-docs/project-intro.md
new file mode 100644
index 0000000000..04b6e140c0
--- /dev/null
+++ b/src/content/api-docs/project-intro.md
@@ -0,0 +1,7 @@
+A Neon project is the top-level container for your Postgres workload. It holds branches, compute endpoints, roles, and databases, plus the Postgres version, region, and project-wide settings.
+
+## When to use this API
+
+Use these endpoints to create, update, delete, or recover projects from automation and provisioning scripts. For one-off work, the [Neon Console](https://console.neon.tech) and [Neon CLI](https://neon.com/docs/reference/cli-projects) cover the same operations.
+
+See [Manage projects](https://neon.com/docs/manage/projects) for plan limits, restoration, and ownership transfer.
diff --git a/src/content/api-docs/snapshot-intro.md b/src/content/api-docs/snapshot-intro.md
new file mode 100644
index 0000000000..1c9835d499
--- /dev/null
+++ b/src/content/api-docs/snapshot-intro.md
@@ -0,0 +1,12 @@
+Snapshots are point-in-time copies of a branch that you can keep as backup or use as the starting point for a new branch. You can create them on demand, and on paid plans Neon can also create them on a schedule.
+
+## Key constraints
+
+- Manual snapshots can be created from root branches only.
+- Snapshots are distinct from [branches](#tag/branch). A branch gives you a full live Postgres instance at a past moment; a snapshot is a lighter-weight stored copy.
+
+## When to use this API
+
+Use these endpoints to create snapshots manually, list them, restore from them, or delete them. Scheduled snapshots are managed for you; you interact with them mainly when restoring.
+
+See [Backup and restore](https://neon.com/docs/guides/backup-restore) for plan limits, pricing, and usage details.
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000000..0e43958a4b
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,39 @@
+{
+ "compilerOptions": {
+ "baseUrl": "src",
+ "target": "ES2017",
+ "lib": [
+ "dom",
+ "dom.iterable",
+ "esnext"
+ ],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": false,
+ "noEmit": true,
+ "incremental": true,
+ "module": "esnext",
+ "esModuleInterop": true,
+ "moduleResolution": "node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ]
+ },
+ "include": [
+ "next-env.d.ts",
+ ".next/types/**/*.ts",
+ ".next/dev/types/**/*.ts",
+ "**/*.mts",
+ "**/*.ts",
+ "**/*.tsx"
+ ],
+ "exclude": [
+ "node_modules",
+ "public"
+ ]
+}