Claimable Postgres

Instant Postgres databases for local development, demos, prototyping, and test environments. No account required. Databases expire after 72 hours unless claimed to a Neon account.

Quick Start

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

Parse

connection_string

claim_url

connection_string

.env

DATABASE_URL

For other methods (CLI, SDK, Vite plugin), see Which Method? below.

Which Method?

• REST API: Returns structured JSON. No runtime dependency beyond

  curl

  . Preferred when the agent needs predictable output and error handling.
• CLI (

  npx neon-new@latest --yes

  ): Provisions and writes

  .env

  in one command. Convenient when Node.js is available and the user wants a simple setup.
• SDK (

  neon-new/sdk

  ): Scripts or programmatic provisioning in Node.js.
• Vite plugin (

  vite-plugin-neon-new

  ): Auto-provisions on

  vite dev

  if

  DATABASE_URL

  is missing. Use when the user has a Vite project.
• Browser: User cannot run CLI or API. Direct to https://neon.new.

REST API

Base URL:

https://neon.new/api/v1

Create a database

curl -s -X POST "https://neon.new/api/v1/database" \
  -H "Content-Type: application/json" \
  -d '{"ref": "agent-skills"}'

ref

"agent-skills"

enable_logical_replication

The

connection_string

-pooler

Response:

{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://...",
  "claim_url": "https://neon.new/claim/019beb39-...",
  "expires_at": "2026-01-26T14:19:14.580Z",
  "created_at": "2026-01-23T14:19:14.580Z",
  "updated_at": "2026-01-23T14:19:14.580Z"
}

Check status

curl -s "https://neon.new/api/v1/database/{id}"

Returns the same response shape. Status transitions:

UNCLAIMED

CLAIMING

CLAIMED

connection_string

null

Error responses

ref

Missing referrer

Database not found

Failed to create the database.

CLI

npx neon-new@latest --yes

Provisions a database and writes the connection string to

.env

@latest

--yes

Pre-run Check

Check if

DATABASE_URL

.env

If the key exists, offer the user three options:

1. Remove or comment out the existing line, then rerun.
2. Use

   --env

   to write to a different file (e.g.

   --env .env.local

   ).
3. Use

   --key

   to write under a different variable name.

Get confirmation before proceeding.

Options

--yes

-y

false

--env

-e

./.env

--key

-k

DATABASE_URL

--prefix

-p

PUBLIC_

--seed

-s

--logical-replication

-L

false

--ref

-r

agent-skills

Alternative package managers:

yarn dlx neon-new@latest

pnpm dlx neon-new@latest

bunx neon-new@latest

deno run -A neon-new@latest

Output

The CLI writes to the target

.env

DATABASE_URL=postgresql://...              # pooled (use for application queries)
DATABASE_URL_DIRECT=postgresql://...       # direct (use for migrations, e.g. Prisma)
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...

SDK

Use for scripts and programmatic provisioning flows.

import { instantPostgres } from 'neon-new';

const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } = await instantPostgres({
  referrer: 'agent-skills',
  seed: { type: 'sql-script', path: './init.sql' },
});

Returns

databaseUrl

databaseUrlDirect

claimUrl

claimExpiresAt

referrer

Vite Plugin

For Vite projects,

vite-plugin-neon-new

vite dev

DATABASE_URL

npm install -D vite-plugin-neon-new

Agent Workflow

API path

1. Confirm intent: If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
2. Provision: POST to

   https://neon.new/api/v1/database

   with

   {"ref": "agent-skills"}

   .
3. Parse response: Extract

   connection_string

   ,

   claim_url

   , and

   expires_at

   from the JSON response.
4. Write .env: Write

   DATABASE_URL=<connection_string>

   to the project's

   .env

   (or the user's preferred file and key). Do not overwrite an existing key without confirmation.
5. Seed (if needed): If the user has a seed SQL file, run it against the new database:

   psql "$DATABASE_URL" -f seed.sql
   

6. Report: Tell the user where the connection string was written, which key was used, and share the claim URL. Remind them: the database works now; claim within 72 hours to keep it permanently.
7. Optional: Offer a quick connection test (e.g.

   SELECT 1

   ).

CLI path

1. Check .env: Check the target

   .env

   for an existing

   DATABASE_URL

   (or chosen key). If present, do not run. Offer remove,

   --env

   , or

   --key

   and get confirmation.
2. Confirm intent: If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
3. Gather options: Use defaults unless context suggests otherwise (e.g., user mentions a custom env file, seed SQL, or logical replication).
4. Run: Execute with

   @latest --yes

   plus the confirmed options. Always use

   @latest

   to avoid stale cached versions.

   --yes

   skips interactive prompts that would stall the agent.

   npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
   

5. Verify: Confirm the connection string was written to the intended file.
6. Report: Tell the user where the connection string was written, which key was used, and that a claim URL is in the env file. Remind them: the database works now; claim within 72 hours to keep it permanently.
7. Optional: Offer a quick connection test (e.g.

   SELECT 1

   ).

Output Checklist

Always report:

• Where the connection string was written (e.g.

  .env

  )
• Which variable key was used (

  DATABASE_URL

  or custom key)
• The claim URL (from

  .env

  or API response)
• That unclaimed databases are temporary (72 hours)

Claiming

Claiming is optional. The database works immediately without it. To optionally claim, the user opens the claim URL in a browser, where they sign in or create a Neon account to claim the database.

• API/SDK: Give the user the

  claim_url

  from the create response.
• CLI:

  npx neon-new@latest claim

  reads the claim URL from

  .env

  and opens the browser automatically.

Users cannot claim into Vercel-linked orgs; they must choose another Neon org.

Defaults and Limits

Region cannot be changed for claimable databases. Unclaimed databases have stricter quotas. Claiming resets limits to free plan defaults.

Auto-provisioning

If the agent needs a database to fulfill a task (e.g. "build me a todo app with a real database") and the user has not provided a connection string, provision one via the API and inform the user. Include the claim URL so they can keep it.

Safety and UX Notes

• Do not overwrite existing env vars. Check first, then use

  --env

  or

  --key

  (CLI) or skip writing (API) to avoid conflicts.
• Ask before running destructive seed SQL (

  DROP

  ,

  TRUNCATE

  , mass

  DELETE

  ).
• For production workloads, recommend standard Neon provisioning instead of temporary claimable databases.
• If users need long-term persistence, instruct them to open the claim URL right away.
• After writing credentials to an .env file, check that it's covered by .gitignore. If not, warn the user. Do not modify

  .gitignore

  without confirmation.