feat: add interactive API reference with per-operation pages

.gitignore

@@ -72,6 +72,12 @@ public/docs/**/llms.txt
 public/docs/llms-full.txt
 src/utils/data/github-stars.generated.json
 
+# API ref generator output (never commit — CI regenerates on every deploy)
+src/data/api-ref/
+src/data/api-ref.next/
+public/docs/reference/api/
+public/md/docs/reference/api.next/
+
 # Mac files
 .DS_Store
 

content/api-docs/api-keys.md

@@ -0,0 +1,13 @@
+Neon API keys authenticate all REST API requests. Each key has a scope that limits what it can access — use the narrowest scope that fits your use case.
+
+| Scope          | Access                                               |
+| -------------- | ---------------------------------------------------- |
+| Personal       | All projects you're a member of across organizations |
+| Organization   | All projects in an org (admin-level)                 |
+| Project-scoped | A single project                                     |
+
+Keys are shown once at creation. Store them immediately; Neon cannot retrieve them later. Revoking a key takes effect immediately.
+
+The [Neon CLI](/docs/reference/cli-auth) also supports OAuth-based authentication via `neon auth`, which opens a browser to authorize access without requiring a manually created key.
+
+See [Manage API keys](/docs/manage/api-keys) for rotation strategy and org key management.

content/api-docs/auth-legacy.md

@@ -0,0 +1,3 @@
+> **Deprecated:** These endpoints are from a previous version of Neon Auth. For new integrations, use the [Authentication](/docs/reference/api/auth) endpoints instead.
+
+These endpoints remain available for existing integrations. See [Neon Auth](/docs/auth/overview) for current documentation.

content/api-docs/auth.md

@@ -0,0 +1,7 @@
+Neon Auth is a managed authentication service powered by [Better Auth](https://www.better-auth.com/). It stores users, sessions, and auth configuration directly in your Neon Postgres database, so your auth state [branches with your data](/docs/auth/branching-authentication). Each branch gets its own isolated auth environment.
+
+Common uses include testing sign-up and login flows in preview environments, running end-to-end auth tests in CI without touching production, and provisioning auth as part of platform automation.
+
+These endpoints manage Neon Auth at the branch level: enabling auth, rotating keys, and inspecting configuration. For a full walkthrough of the management API, see [Manage Neon Auth via the API](/docs/auth/guides/manage-auth-api).
+
+For integrating authentication into an application, use the Neon Auth SDKs. See [Neon Auth](/docs/auth/overview) to get started.

content/api-docs/branches.md

@@ -0,0 +1,5 @@
+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. Common uses include per-PR preview environments, testing schema changes before promoting them, and point-in-time recovery.
+
+You cannot delete a project's root branch. You also cannot delete a branch that has children; delete or reparent the children first.
+
+See [Branching with the Neon API](/docs/guides/branching-neon-api) for end-to-end examples, and [Automate branching with GitHub Actions](/docs/guides/branching-github-actions) for CI/CD workflows using Neon's create, delete, reset, and schema diff actions.

content/api-docs/consumption.md

@@ -0,0 +1,13 @@
+The Consumption API returns usage metrics (compute hours, storage, and data transfer) for your account, organization, or individual projects.
+
+## Scope
+
+Metrics are available at three levels:
+
+- **Account**: usage across all projects you own.
+- **Organization**: usage across an organization's projects. See [Organization consumption](/docs/manage/orgs-api-consumption).
+- **Project**: per-project metrics on usage-based plans.
+
+> **Note:** Legacy consumption endpoints exist for older integrations. New code should use the current endpoints. See [Query consumption metrics](/docs/guides/consumption-metrics) for which to use and when.
+
+To reduce usage, see [Cost optimization](/docs/introduction/cost-optimization) and [Reduce network transfer costs](/docs/introduction/network-transfer).

content/api-docs/dataapi.md

@@ -0,0 +1,5 @@
+The Data API is an HTTP SQL endpoint attached to a branch. It lets you run queries over HTTPS without a Postgres driver, useful for edge runtimes, browser clients, or environments where a persistent TCP connection is impractical.
+
+Use these endpoints to enable, configure, or disable the Data API on a branch. To run queries once it's enabled, use the Data API URL returned at setup time.
+
+See [Neon Data API](/docs/data-api/overview) for query syntax, authentication, and usage details.

content/api-docs/endpoints.md

@@ -0,0 +1,7 @@
+In Neon, a compute endpoint is the Postgres instance attached to a branch, not an HTTP endpoint. Applications connect over the standard Postgres protocol.
+
+Each branch has one primary read-write compute and can have multiple read-only computes for read replicas. Read replicas read from the same storage as the primary; no data is duplicated. Computes scale to zero after a period of inactivity (5 minutes by default) and wake automatically on the next connection. You can configure the timeout via `suspend_timeout_seconds`.
+
+Use these endpoints to create, configure, restart, or delete computes. Common uses include adding read replicas, tuning compute size, and adjusting scale-to-zero behavior. Note that changing a compute's size restarts the endpoint and briefly disconnects active connections.
+
+See [Manage computes](/docs/manage/computes) and [Read replicas](/docs/introduction/read-replicas) for configuration details.

content/api-docs/operations.md

@@ -0,0 +1,7 @@
+Operations represent background jobs the Neon Control Plane runs to fulfill API requests: creating branches, starting computes, restoring snapshots, and provisioning databases. Some operations are system-initiated, such as suspending idle computes or running periodic availability checks.
+
+Status values: `scheduling`, `running`, `finished`, `failed`, `cancelling`, `cancelled`, `skipped`. Terminal statuses are `finished`, `skipped`, and `cancelled`. A `failed` operation is not terminal and may be retried.
+
+Neon limits overlapping operations per 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.
+
+See [System operations](/docs/manage/operations) for polling guidance, retry examples, and a full list of operation types.

content/api-docs/organizations.md

@@ -0,0 +1,7 @@
+An organization groups projects under shared billing, access control, and API keys. Organizations have two roles: **Admin** (full control over the org and its projects) and **Member** (access to all projects, but cannot modify org settings).
+
+Use these endpoints from automation that manages team membership, handles invitations, or configures org-level infrastructure. Direct project operations (creating branches, querying databases) use the project-level endpoints regardless of whether the project belongs to an org.
+
+Some endpoints require the admin role. Member-level tokens can read org state but cannot modify members or billing settings.
+
+See [Organizations](/docs/manage/organizations) for full role permissions and plan limits.

content/api-docs/projects.md

@@ -0,0 +1,5 @@
+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 you create a project, Neon provisions a root branch (`main`), a default compute, a `neondb` database, and a matching role automatically.
+
+Use these endpoints to create, update, delete, and list projects from automation and provisioning scripts.
+
+See [Manage projects](/docs/manage/projects) for plan limits, restoration, and ownership transfer.

content/api-docs/regions.md

@@ -0,0 +1,5 @@
+This is a read-only reference endpoint. It returns the available regions where Neon projects can be created, with each region's ID and display name.
+
+Use the `region_id` from this response when creating a project. Region is set at creation and cannot be changed.
+
+See [Regions](/docs/introduction/regions) for availability and latency considerations.

content/api-docs/snapshots.md

@@ -0,0 +1,7 @@
+Snapshots are point-in-time copies of a branch stored without an attached compute. You can create them on demand (1 on the Free plan, 10 on paid plans); paid plans also support scheduled snapshots, which don't count toward the manual limit.
+
+Manual snapshots can only be created from root branches. Unlike a branch, a snapshot has no attached compute; it's a stored backup copy you restore from rather than connect to directly.
+
+Use these endpoints to create snapshots manually, list them, restore from them, or delete them. Scheduled snapshots are managed automatically; you interact with them mainly when restoring.
+
+See [Backup and restore](/docs/guides/backup-restore) for pricing and usage details.

content/api-docs/users.md

@@ -0,0 +1,3 @@
+These endpoints return information about the currently authenticated user: your user ID, email, and organization memberships. They act on the identity tied to the API key, not on a specific project.
+
+See [Manage your account](/docs/manage/accounts) for account settings and profile management.