neon-postgres-agent-platforms

Neon AI Agent Program

Companion to neon-postgres (install that first). This skill covers fleet-scale control plane for the Neon Agent Program: dual-org layout, project transfer, per-tenant provisioning, compound checkpoints, consumption, and commercial terms.

For connection strings, drivers, ORMs, branching tutorials, Auth in apps, Data API, and MCP, use neon-postgres and Neon docs.

Scope

Use neon-postgres for general Neon usage. Use this skill when the question involves:

• Dual-org economics and API keys (personal, organization, project-scoped)
• Project-per-tenant provisioning and transfer
• Fleet-wide snapshot/restore orchestration and housekeeping
• Compound checkpoints
• Consumption polling for metered fleets
• Agent Plan commercial terms (with links, not invented numbers)
• Partner support paths

Install Skills

npx skills add neondatabase/agent-skills -s neon-postgres

Assistants: what you can do after install

With neon-postgres and this skill loaded, you have enough context for platform-level Neon work: dual-org layout, provisioning a project for a new tenant, compound checkpoints, org-wide consumption polling, and transfer/upgrade flows—without the user pasting long documentation.

Where runnable examples live: TypeScript samples run from this skill’s scripts/ directory (package.json, npm run …). The references/ directory keeps markdown guides beside the runnable examples; MANAGEMENT_API_SAMPLES.md is the script catalog and env map. The human Quick start is the root README.

Gotchas

Non-obvious facts agents often get wrong:

• Checkpoints are compound records. A tenant checkpoint includes source

revision + Neon snapshot/branch + secrets/env version + deploy URL + agent metadata. Do not equate "checkpoint" with "Neon branch" alone. See the compound checkpoints doc.

• Cross-org transfer needs a personal API key (org keys only work

inside one org). Projects with GitHub or Vercel integrations in Neon cannot be transferred; the API returns 422 (Transfer projects).

• After a finalized snapshot restore, the active branch ID changes. Poll

operations to completion before reconnecting. Delete orphaned (old) branches to avoid storage cost.

• Billing-aligned usage: prefer

GET /api/v2/consumption_history/v2/projects over legacy consumption endpoints. GET /api/v2/consumption_history/account is deprecated with a planned sunset of 2026-06-01; migrate to the v2 per-project endpoint (legacy consumption guide).

• V2 metrics parameter values (for implementers): compute_unit_seconds,

root_branch_bytes_month, child_branch_bytes_month, instant_restore_bytes_month, snapshot_storage_bytes_month, public_network_transfer_bytes, private_network_transfer_bytes, extra_branches_month (consumption metrics).

• Snapshot schedules are not provided on Agent Plan. Partners implement via

snapshot API + their own scheduler.

• Rates and caps: never invent dollar amounts or limits. Confirm on live

neon.com docs.

Agent Plan and two organizations

Partners run two Neon organizations:

| Org | Role | | ---------------------- | ------------------------------------------ | | Sponsored free org | Free-tier end users (within program rules) | | Paid org | Paying customers (metered per Agent Plan) |

Key points:

• Dollar rates, credits, and project caps come only from the live

Agent Plan and neon.com/agents. Do not invent numbers.

• Organization API key: automation inside one org (create project, set

quotas).

• Personal API key: required to transfer a project between orgs when a

customer changes tier, then PATCH quotas to match the new tier.

• Project-scoped API key: member-level access to one project only—narrower than an org key and useful for per-tenant runtime or automation that must not touch the rest of the org. Cannot create new projects org-wide; invalid if the project is transferred out of the org.

Links: Agent Plan · AI Agents · Project transfer · AI Agent integration

HIPAA

• Agent Plan includes HIPAA with no extra fee. Partners must still follow

Neon's published HIPAA program (workflows, agreements, configuration).

• To get access or start the process, reach out to your **primary Neon

contact**.

• This skill is not legal advice.

Link: HIPAA on Neon

Fleet shape: project-per-tenant

• Project-per-tenant is Neon's documented fleet pattern: each tenant you

provision for (an end user, a customer app, or an agent workload) gets its own dedicated Neon project. That project is the isolation boundary for branches, databases, roles, and computes—not a shared Postgres cluster where you only partition by schema.

• Isolation and billing: Separate projects give **complete data and resource

isolation between tenants, keep consumption limits and billing straightforward at project scale (aligned with Agent Plan metering elsewhere in this skill), and match how the Neon Management API and Console are structured** (project-scoped create, quota, and lifecycle calls).

Staging and production

• For each tenant project, treat staging versus production (and ephemeral

previews) as branch- and snapshot-driven lifecycle inside that project—use Snapshots and database versioning and Sandbox and preview databases below for fleet orchestration, not a second project by default.

• Agent and app builders: separate your platform's environments (for

example how you host the builder or control plane) from each tenant's staging and production branches—avoid conflating "our production service" with "the tenant's production branch" in ledgers and automation.

• Some embedded products also split an end customer's **production and

development Neon assets across separate orgs for trust, keys, and billing boundaries; when that applies, read Isolation beyond branches (project and org edge cases)** next.

Link: AI Agent integration guide

Isolation beyond branches (project and org edge cases)

Use project- or org-level splits when tenant scope or trust needs go beyond branch- and snapshot-first staging and production in Fleet shape. Embedded products may isolate an end customer's production versus development databases across separate Neon orgs, not only branches—tighter billing, org API keys, and console boundaries while you still manage branches within each org.

Project-level isolation (multiple projects per tenant or workload):

• Stronger blast radius if a connection string or role is compromised—one

leak should n