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. The legacy account-level endpoint has been retired; use 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 not span unrelated workloads.

• Separate operational lifecycles (for example a disposable analytics or

migration sandbox versus production data) when automation or ownership would

otherwise collide in one Postgres.

• Different teams or automation with conflicting migration or admin rights.
• Harder compliance or data-mixing rules where a single database must not

host combined workloads.

Each extra project adds fleet surface area: more API keys, more consumption

rows, more housekeeping, and higher operational cost—keep project-per-tenant

as the default unless a boundary above clearly applies.

Org-level isolation (beyond sponsored free versus paid):

• The two-organization layout in Agent Plan and two organizations is

the commercial split (free-tier users versus paying customers). That pattern

can stack with an embedded product split: for example **prod org versus dev

org per end customer** so playground databases never share org scope with shipped

production. Keep a clear internal map of which org owns which environment and

tier.

• Separately, partners sometimes need additional Neon orgs or accounts for

contracting (enterprise “their org only”), reseller or MSP models, or

geographic or legal separation—product defaults and limits belong on live docs;

do not invent caps.

• Organization API keys are scoped to one org. Cross-org moves use a

personal API key and project transfer, as in Gotchas—do not assume an

org key can operate across orgs. Project-scoped keys are further limited to a

single project (API keys).

Embedding hygiene:

• Map each platform service (control plane, tenant runtime, billing or

consumption jobs) to least-privilege keys; do not reuse production keys in

sandboxes at the wrong layer.

• When prod and dev for an end customer live in different Neon orgs, scope

automation per org (typically one organization API key per org) and persist

org_id with project_id / branch_id so jobs and restores target the correct

side.

• Keep your ledger (project_id, branch_id, org, checkpoint metadata)

aligned with the isolation layer you chose so restores, transfers, and audits

stay consistent.

Snapshots and database versioning

For snapshot semantics, active-branch patterns, and restore tutorials, defer to

neon-postgres and

AI database versioning.

Here, emphasize tenant fleets:

• Persist snapshot and branch IDs per tenant in your ledger. Tie each to

non-Neon state via

compound checkpoints.

• After finalized restores, branch IDs change and orphaned (old) branches

accumulate. Automate cleanup and update stored IDs.

• Poll operations to completion before reconnecting tenant apps.
• Product semantics (snapshot counts per tier, Beta pricing dates) change.

Confirm on Agent Plan docs.

Typical platform-level checkpoint triggers:

• Before promoting generated schema changes for a tenant
• Start or end of an agent run that mutates a tenant's database
• Before destructive migrations or customer-visible restore actions

Links:

AI database versioning ·

Backup and restore ·

Snapshots-as-checkpoints demo

Sandbox and preview databases

Use this when a partner needs per-tenant preview or sandbox databases for

generated apps. ("How do I create a branch?" for a single app goes to

neon-postgres.)

• Track project_id / branch_id per customer / agent run when spinning

previews via the Management API.

• Branch and storage counts scale with fleet size. Monitor caps and

garbage-collect idle previews.

• Short suspend_timeout_seconds on preview computes reduces cost.
• Pair branch/snapshot lifecycle with secrets rotation and deploy URLs via

compound checkpoints.

Link:

AI Agent integration guide

Cost, consumption, and entitlements

• Never invent pricing, quotas, or limits. Confirm on

Agent Plan and

consumption metrics.

• Use GET /api/v2/consumption_history/v2/projects for billing-aligned fields.

Legacy endpoints differ. The legacy account-level endpoint has been retired;

use v2 per-project metrics instead

(legacy guide).

• V2 metrics query strings are exactly: 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.

• Poll consumption roughly every 15 minutes. Polling does not wake suspended

computes.

• Run auth-users.ts meta from

scripts/

for a routing map (Neon Auth REST vs Postgres roles vs consumption APIs).

Links:

Agent Plan ·

Consumption metrics ·

Consumption limits ·

Cost optimization ·

Plans

Organization and project limit increases

• Current defaults and ceilings are on

Agent Plan and

AI Agent integration.

Do not invent limits.

• For project increase requests, email

[email protected] with org ID(s), growth context,

and timeline. Also flag in shared Slack if available.

Co-marketing

• Co-marketing is an included Agent Plan benefit.
• Available: joint blog posts, social promotion, hackathon sponsorship, case

studies, landing page features.

• Reach out via shared Slack or your Neon representative with context on what

you're building.

Link: Agent Plan

Support

• Shared Slack channel: fastest path for technical questions and urgent

issues.

• Neon representative: account-level requests, custom configuration,

escalations.

• Limit increases: email

[email protected] with org ID(s), growth context,

and timeline.

• Billing: raise via Slack or your Neon representative. Credit balances and

invoices are in the Neon Console under Billing.

• Community: Neon Discord ·

Docs ·

API reference

Repository samples

Runnable Management API automation from

neondatabase/neon-for-agent-platforms.

• Quick start:

README

• Script catalog:

MANAGEMENT_API_SAMPLES.md

• Compound checkpoints:

COMPOUND_CHECKPOINTS_FOR_AGENT_PLATFORMS.md

• Checkpoint orchestration:

CHECKPOINT_ORCHESTRATION_PATTERN.md

• Doc index:

SCRIPT-OVERVIEW.md

All scripts use @neon/sdk only. Shared

utils.ts

builds the client and resolves the default branch; the SDK polls async

operations (readiness) for you. For SQL access from app code (drivers, pooling, ORMs),

use neon-postgres.