docs: resolve verified public source inconsistencies

[KyleAMathews]

Summary

This PR corrects verified mismatches between Neon’s website, public OpenAPI contract, published packages, and executable SDK/CLI source. The edits are intentionally narrow: they preserve the existing tone and page structure, keep “branch your whole backend” as the product framing, and move unresolved implementation questions to this PR instead of exposing uncertainty in customer documentation.

Users get accurate lifecycle, availability, branching, package, and SDK guidance. No product code or API contract changes in this PR.

Root cause

These pages describe interfaces that evolve in separate repositories and projections. Several claims remained tied to earlier API shapes, package releases, or CLI behavior after the authoritative contract or executable source changed. In a few places, two website pages also contradicted each other.

Approach

• Rechecked every Neon conflict family from the field survey against current first-party sources.
• Changed customer docs only when a current contract, executable source, published package, or product-specific page resolves the mismatch directly.
• Incorporated product-owner review where leaked pre-release API artifacts were not authoritative for current availability.
• Preserved existing presentation wherever possible. The larger backend-overview edit is limited to adding the already-supported Data API and qualifying the lifecycle mechanics behind whole-backend branching.
• Kept unresolved runtime and source-owner questions in Engineering questions, with sources for both sides.

Key invariants

• “Branch your whole backend” remains the user-facing model; the docs no longer claim every service uses Postgres-style copy-on-write.
• Customer docs contain resolved guidance, not speculation about undocumented runtime behavior.
• Unreleased Branch Recovery behavior remains out of customer docs and is tracked in its standing draft PR.
• Package contracts, OpenAPI, executable source, and observed runtime are treated as different evidence types.
• Every correction below links the previous claim and the source used to resolve it.

Correction ledger

The website baseline for stale claims is neondatabase/website@23681e7. The live Neon OpenAPI v2 contract was rechecked on 2026-08-31 (SHA-256 d5bff604e6a0fd3676010eeca721e292c23d41d7f7f07c730b53c712426b5394). Executable-source checks use neondatabase/neon-pkgs@bf9b4c8, neondatabase/neon-api-python@a3ad034, and neondatabase/neon-js@029a336.

Area	Mismatch and sources	Correction
Operation status	Two website pages omitted error and called failed nonterminal (API-docs claim, Manage operations claim). OpenAPI describes eight statuses and says both failed and error have ended. The SDK waiter likewise treats failed, error, and cancelled as terminal failures. OpenAPI retains failures_count and retry_at as retry history.	Updates both pages with all eight statuses, terminal success/failure classifications, and the retry-history fields.
Branch Recovery artifacts	The TypeScript SDK docs listed branches.recover(), but SDK 2.0.0 removed it when the route left OpenAPI (SDK changelog). OpenAPI still leaks seven-day recovery and hard_delete text, but the website previously reverted Branch Recovery docs because the feature was not live, and product-owner review confirms it remains unavailable.	Leaves the current permanent-deletion guidance in place and removes the nonexistent SDK wrapper. Launch documentation remains in draft PR #5198.
Managed Better Auth regions	The backend overview said Auth worked in any region (previous claim), while the product page says AWS only and new projects are offered only in AWS.	Says Postgres and Managed Better Auth are available in all regions offered for new projects, avoiding obsolete Azure framing on the orientation page.
Managed Better Auth database selection	The branching page said only the default database was supported (previous claim). The Auth API guide documents database_name, and OpenAPI says omission selects the default database.	Documents the default and explicit-database cases while retaining the read-write endpoint requirement.
Data API membership	The backend overview enumerated five capabilities (previous list). The neon.ts reference defines Data API as a service and its NEON_DATA_API_URL projection; the glossary also lists all six backend services.	Adds Data API to the overview, capability table, and agent prompt, while stating that the example itself uses five services because its Function queries Postgres directly.
Whole-backend branching mechanics	The overview said the database, buckets, and Functions all fork copy-on-write (previous claim). Product-specific sources describe different mechanics: Storage is copy-on-write; each branch runs its own Function URL, isolated Auth environment, attached Data API endpoint, and AI Gateway endpoint. AI Gateway credentials are valid on their issuing branch and descendants.	Preserves “branch your whole backend,” but explains that services follow the branch through service-specific mechanics rather than universal copy-on-write.
Object Storage log severity	The detailed Storage page classified all 5xx responses as ERROR, then said unsupported 501 responses are WARN (conflicting statements).	Adds the documented 501 exception to the table.
Python SDK route drift	Package metadata says 0.3.0. Its client calls set_as_primary, revokes permissions at the collection with a body (source, current permission-item route), and reveals passwords with POST (source). Current API routes use set_as_default, a permission-id path, and GET for password retrieval.	Adds a versioned compatibility warning and recommends the REST API or TypeScript SDK for those three operations. It does not claim that undocumented runtime aliases fail.
Config-runtime credential discovery	The docs promised environment and credential-file fallbacks (previous authentication section). Executable source reads neither and requires an explicit apiKey unless an api adapter is supplied; only the production host has an internal default (source). The same source retains the Console API-key recovery link.	Corrects authentication, option tables, examples, CI guidance, and error behavior while preserving the API-key creation link.
neon-js publication	Three pages warned that single-URL initialization was not on npm (one previous warning). npm published @neondatabase/neon-js@0.7.0-beta on 2026-08-11; tagged source implements the single-URL form.	Makes the single-URL form primary and keeps the object form as explicit compatibility guidance for 0.6.2-beta and earlier.
WebSockets under neon dev	The guide said local upgrades returned 200 instead of 101 (previous warning). Local upgrade support first shipped in neonctl 2.45.0 on 2026-08-06; its changelog calls out local upgrade support, and the tagged runtime installs the listener.	Documents local testing for 2.45.0 and later, while retaining the 200-versus-101 behavior and deployed-testing path for earlier versions.
Logical replication	The compatibility table said wal_level=logical was coming soon (previous claim), while current docs provide Console and API enablement.	Says wal_level defaults to replica and becomes logical when logical replication is enabled.
Project deletion and recovery	The project page called deletion irreversible and permanent (settings claim, delete section), while the same page documents a seven-day recovery window and explicit exclusions. OpenAPI publishes POST /projects/{project_id}/recover.	Corrects the early warnings and narrows “all data and configuration intact” to the page’s enumerated recovery behavior.
New-project regions	The Regions page broadly said new projects deploy to AWS and Azure (previous claim). The shared deprecation notice says new Azure projects can no longer be created, and OpenAPI’s Project.platform_id currently says only AWS is supported.	Keeps the summary and opening focused on current AWS project creation. The dedicated Azure deprecation section and Azure NAT IPs remain for existing-project users.

Version and rollout audit

Dates below are the earliest verified public evidence, not inferred backend rollout dates. Dual instructions are limited to client package versions that users can still have installed.

Area	Earliest verified public evidence	Compatibility treatment
Operation terminal states	@neon/sdk classified failed, error, and cancelled as failures by its first 0.1.0 release on 2026-06-25 (source commit).	No dual instructions. This is a server/API contract correction.
Managed Better Auth regions	AWS-only availability was documented on 2025-12-04 (commit) before the 2025-12-12 launch (changelog).	No dual instructions. The broader umbrella-page claim was never valid for the launched service.
Managed Better Auth database selection	database_name was documented by 2026-03-05 (commit).	No dual instructions. This is a server API field; the default case remains documented.
Data API in neon.ts	Data API configuration and NEON_DATA_API_URL were documented on 2026-06-16 (commit).	No old path to retain. The overview now includes the already-supported sixth service.
Whole-backend branching	Service-specific mechanics were documented by the Functions material on 2026-06-24; the composite backend entered public beta by 2026-07-17 (changelog).	Keep “branch your whole backend” and the concise database/buckets/Functions outcome; replace only the inaccurate universal copy-on-write mechanism.
Object Storage log severity	The Storage Logs page contained both the status table and the 501 → WARN exception when introduced on 2026-07-14 (commit).	No dual instructions. This resolves an internal page contradiction; emitted runtime severity remains an engineering question.
Python SDK routes	neon-api 0.3.0 remains the latest package, published 2025-01-16 (PyPI); its route shapes differ from current OpenAPI.	Keep both truths: document the published package surface and warn that three operations should use REST or the TypeScript SDK.
Config-runtime credentials	Ambient environment/CLI credential discovery was removed in 0.12.0 on 2026-08-03 (changelog); every /v1 release requires explicit credentials.	No parallel legacy workflow in the /v1 reference. Keep the current explicit-key path and the still-valid Console key link.
neon-js initialization	Single-URL initialization first shipped in 0.7.0-beta on 2026-08-11 (package, tagged source).	Show both: single URL for 0.7.0-beta+, object form for 0.6.2-beta and earlier.
Local WebSockets	Local upgrade support first shipped in neonctl 2.45.0 on 2026-08-06 (changelog).	Show both: local testing for 2.45.0+, deployed testing or upgrade for earlier CLIs.
Logical replication	wal_level=logical behavior was documented in December 2023 and logical replication launched to all users on 2023-12-23 (changelog).	No dual instructions. The “coming soon” table entry was already stale when added in May 2024.
Project recovery	Seven-day recovery entered docs on 2025-12-15 (commit); its exclusions were present from the start.	No dual instructions. Earlier permanent-deletion text contradicted the recovery section on the same page.
Branch Recovery attempts	Docs were added and reverted as not live on 2026-07-02 (revert); the SDK later added and removed a recovery wrapper. Product-owner review confirms these were failed release attempts, not a supported rollout.	No customer instructions until launch. Keep permanent-deletion guidance and use draft PR #5198 for the eventual release.
New-project regions	Azure deprecation was announced in April 2026; the unqualified no-new-Azure-projects guidance was documented by 2026-07-03 (commit).	No dual instructions. Region availability is server/account policy, while existing Azure projects remain documented separately.

Reviewer-confirmed release state

Branch Recovery is not currently available. The OpenAPI deletion text and earlier SDK wrapper are leaked pre-release artifacts from several failed release attempts. This PR does not publish that behavior; draft PR #5198 remains the launch destination, including final validation of child-branch behavior.

Engineering questions

These source conflicts were rechecked but are intentionally not presented as settled customer guidance:

• Managed Better Auth database recommendation: The corrected note preserves the default database name and documents the supported database_name override. The previous note also called one database per branch the recommended pattern, but no current product or API source found in this audit repeats that recommendation. Should the recommendation be restored, and if so, where is its current source of truth?
• functions:invoke enforcement: OpenAPI includes functions:invoke in CredentialScope, while the Functions authentication page describes a public URL with handler-owned authentication. Is the scope enforced, reserved, or stale?
• Storage severity across pages: CLI docs say Storage records are all INFO, while the Storage page documents INFO/WARN/ERROR by status code. The local inconsistency on the Storage page is fixed, but emitted runtime severity still needs an implementation or live-sample check.
• Logs release label: Website and CLI docs call Logs beta; OpenAPI labels queryProjectBranchLogs, listProjectBranchLogFields, and listProjectBranchLogFieldValues Private Beta. This needs API-owner confirmation, so this PR leaves customer-facing release wording unchanged.
• Python SDK user agent: The 0.3.0 package still emits neon-client/python version=(0.1.0). This is a package-source issue and does not require a website claim.
• Legacy project-scoped Auth routes: OpenAPI still publishes legacy routes with removal dates that passed on 2026-03-01. Current product docs already use branch-scoped routes; execution was not tested.
• CLI function versus functions: The package README lists singular function, while executable registration makes functions canonical and function an alias. Website command docs already use the canonical form.

Non-goals and trade-offs

• No authenticated Neon project was created or mutated, so runtime tolerance for outdated Python routes remains unobserved.
• Branch Recovery launch content and child-branch validation are deferred to draft PR #5198.
• This PR does not change OpenAPI, SDK, CLI, or package source; it records those owner questions above.
• Projection-specific differences that compose correctly, such as Console production versus API/CLI main, are not treated as contradictions.
• Peer-product findings from the field survey are outside this repository.

Verification

npx prettier --check $(git diff --name-only origin/main...HEAD)
npm run check:docs
npm run check:docs-api-consistency
npm run check:content-data
npm run check:api-ref-generated
npm run test:unit:run

• Docs checks: 52 tests passed.
• Unit tests: 807 tests passed on the final rebased commits.
• Changeset: not applicable; this repository has no .changeset/config.json.

Files changed

• content/api-docs/operations.md, content/docs/manage/operations.md: operation status contract and retry history.
• content/docs/auth/branching-authentication.md: Auth default and explicit database selection.
• content/docs/compute/functions/websockets.md: versioned local WebSocket behavior.
• content/docs/data-api/access-control.md, content/docs/data-api/get-started.md, content/docs/reference/javascript-sdk.md: current neon-js initialization with the pre-0.7.0-beta path retained.
• content/docs/get-started/backend-overview.md, public/prompts/neon-backend.md: Data API membership and service-specific lifecycle details while preserving whole-backend framing.
• content/docs/introduction/regions.md: current new-project region availability.
• content/docs/manage/branches.md, content/docs/reference/typescript-sdk.md: retain current branch-deletion guidance and remove the unavailable SDK recovery method.
• content/docs/manage/projects.md: project deletion and recovery consistency.
• content/docs/reference/compatibility.md: logical replication availability.
• content/docs/reference/config-runtime.md: explicit credential and host behavior plus the API-key creation link.
• content/docs/reference/python-sdk.md: versioned route compatibility warning.
• content/docs/storage/logs.md: documented 501 severity exception.

[vercel]

@KyleAMathews is attempting to deploy a commit to the neondatabase Team on Vercel.

A member of the Team first needs to authorize it.

[danieltprice]

Suggested change

Object Storage, Functions, and the AI Gateway are in beta and available only in **AWS US East (Ohio) (`aws-us-east-2`)**, on new or existing projects in that region, so use a project there to try them. Postgres is available in every supported region. Managed Better Auth is available in AWS regions, but not Azure regions. The three new beta services are free to use during beta, subject to usage limits. The AI Gateway is only available on paid plans; the other two are on any plan.

Object Storage, Functions, and the AI Gateway are in beta and available only in **AWS US East (Ohio) (`aws-us-east-2`)**, on new or existing projects in that region, so use a project there to try them. Postgres and Managed Better Auth are available in all supported regions. The three new beta services are free to use during beta, subject to usage limits. The AI Gateway is only available on paid plans; the other two are on any plan.

[KyleAMathews]

Updated this to say Postgres and Managed Better Auth are available in all regions offered for new projects. That keeps the concise framing while making the scope explicit.

[danieltprice]

Neon no longer supports Azure regions.

[KyleAMathews]

Adjusted the overview to avoid mentioning Azure. The dedicated Azure deprecation material remains on the Regions page for existing-project users.

[danieltprice]

Let's not mention Azure regions at all since they are no longer available for new projects.

[KyleAMathews]

Removed Azure from the Regions summary and opening. I retained the dedicated deprecation section and Azure NAT IPs because existing Azure projects still need that guidance.

[danieltprice]

Suggested change

	- **Delete**: Use with care! This action deletes your entire project and all its objects. You can recover it within seven days; after that, deletion is permanent.
	- **Delete**: Use with care. This action deletes your entire project and all its objects. You can recover it within seven days; after that, deletion is permanent.

[KyleAMathews]

Applied verbatim.

[philip]

Love it, left a few comments with one change request.

[philip]

This is great, but branch recovery development is still ongoing. It's not yet available despite a few API references leaking through along the way.

[KyleAMathews]

Thanks for clarifying the release state. I removed the Branch Recovery and hard_delete guidance, restored the current permanent-deletion wording, and updated the PR body to treat the OpenAPI/SDK references as leaked pre-release artifacts. The eventual launch docs remain in draft PR #5198.

[philip]

Thank you for spotting this! This doc PR was waiting for the backend release that, as you noted, is here now. I'll re-test and clean up the PR.

[KyleAMathews]

Thanks. I kept the narrow CLI version boundary here; #5484 can supersede it with the fuller upgradeWebSocket guidance after your retest.

[philip]

Excellent, we must fully address this SDK soon. Either update (likely means rewriting completely) or deprecate. Your note is a great start!

[KyleAMathews]

Thanks. I kept this as the interim warning; the existing Python SDK issues #16, #17, and #18 capture the broader broken-method and schema-drift work.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
neon-next	Ready	Preview	Sep 1, 2026 2:28pm UTC