Neon API for AI agent platforms

Agent plan structure

Neon creates two organizations in your account to separate user tiers:

• Sponsored org (free to you): Project-level limits similar to the Neon free tier. Use for your free users.
• Paid org (with credits): Credits cover charges until depleted. Use for your paying users.

Default cap: 30,000 projects per org (adjustable on request). You're admin on both orgs. Request limit increases when needed.

Each user application gets its own isolated PostgreSQL database that provisions in ~500ms, scales to zero when idle, and supports full version history through snapshots. For additional details, see the agent plan's pricing page.

API operations

Working demo

Pattern in action: https://snapshots-as-checkpoints-demo.vercel.app/

Repo: https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo

Architecture: Meta DB (users, projects, checkpoints) + per-user app DB (one Neon project per session).

Application provisioning

Choose org based on your user's tier:

• Sponsored org → free users
• Paid org → paying users

Transfer projects between orgs when users upgrade from free to paid.

curl -X POST "https://console.neon.tech/api/v2/projects" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user123-app",
    "org_id": "org_id_here",
    "branch": {
      "name": "main",
      "role_name": "app_user",
      "database_name": "app_db"
    },
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 1,
      "suspend_timeout_seconds": 300
    },
    "pg_version": 17,
    "region_id": "aws-us-east-2"
  }'

Create development branches

Create isolated dev environments:

curl -X POST "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": {
      "parent_id": "$PARENT_BRANCH_ID",
      "name": "feature-new-ui"
    },
    "endpoints": [{
      "type": "read_write",
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 0.5
    }]
  }'

Each branch gets a new connection string. For versioning that preserves connection strings, use snapshots.

Autoscaling configuration

Neon autoscales based on CPU (<90%), memory (<75%), and cache (<75%). Set min/max CU ranges per endpoint.

For additional information, see the autoscaling documentation.

Update limits

curl -X PATCH "https://console.neon.tech/api/v2/projects/$PROJECT_ID/endpoints/$ENDPOINT_ID" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 4
    }
  }'

Disable suspend (optional)

To avoid cold starts on critical endpoints, you can prevent suspension. This keeps compute always on and increases cost. Note: suspend_timeout_seconds: 0 uses the default timeout; set to -1 to disable suspension.

curl -X PATCH "https://console.neon.tech/api/v2/projects/$PROJECT_ID/endpoints/$ENDPOINT_ID" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": {
      "suspend_timeout_seconds": -1
    }
  }'

Cost implications: Compute usage is billed continuously when suspension is disabled.

Authentication setup

Neon Auth syncs user data to your database automatically. See how it works.

Initialize

curl -X POST "https://console.neon.tech/api/v2/projects/auth/create" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_provider": "stack",
    "project_id": "$PROJECT_ID",
    "branch_id": "$BRANCH_ID",
    "database_name": "app_db",
    "role_name": "app_user"
  }'

Response includes pub_client_key, secret_server_key, and jwks_url.

Generate SDK keys

curl -X POST "https://console.neon.tech/api/v2/projects/auth/keys" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "$PROJECT_ID",
    "auth_provider": "stack"
  }'

Configure OAuth

# Dev (shared keys)
curl -X POST "https://console.neon.tech/api/v2/projects/$PROJECT_ID/auth/oauth_providers" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "google"}'

# Production (custom keys)
curl -X POST "https://console.neon.tech/api/v2/projects/$PROJECT_ID/auth/oauth_providers" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "github",
    "client_id": "Iv1.xxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }'

Available providers: github, google, microsoft

Query users

Users sync automatically:

SELECT id, email, name, signed_in_at
FROM neon_auth.users_sync
WHERE email_verified = true
ORDER BY created_at DESC;

Database versioning

Snapshot schema and data at any moment. Users can roll back, preview earlier states, or test changes safely.

See database versioning with snapshots for complete workflow including restore and cleanup.

Point-in-time recovery

Create branch at past timestamp without pre-created snapshot:

curl -X POST "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": {
      "parent_id": "$ROOT_BRANCH_ID",
      "name": "pitr-2025-01-16-1420",
      "parent_timestamp": "2025-01-16T14:20:00Z"
    }
  }'

Data API

Transform tables into REST endpoints. PostgREST-compatible.

curl -X POST "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/data-api/app_db" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_provider": "neon_auth"}'

Response includes endpoint URL. Use standard HTTP verbs (GET, POST, PATCH, DELETE). See Data API guide.

Project transfer between organizations

Move user projects from sponsored to paid org when they upgrade:

curl -X POST "https://console.neon.tech/api/v2/organizations/$SOURCE_ORG_ID/projects/transfer" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_ids": ["$PROJECT_ID_1", "$PROJECT_ID_2"],
    "destination_org_id": "$DEST_ORG_ID"
  }'

Requires personal API key with access to both orgs. Transfer up to 400 projects per request.

See transfer projects between organizations for details.

Get project consumption

Track compute time, storage, and network I/O per project. See consumption metrics guide.

Best practices

Connection management

• Use pooled connections (-pooler) for serverless
• Use direct connections for long-running servers
• See connection limits

Cost optimization

• Set autoscaling_limit_min_cu: 0.25 for scale-to-zero
• Use 300-900s suspend_timeout_seconds
• Smaller compute for dev branches
• Delete orphaned "(old)" branches after restore
• Disable suspend on critical endpoints to eliminate cold starts (increases cost)

Resources

• Neon database versioning guide
• Neon API reference
• Neon platform integration guide
• Neon OpenAPI specification
• Neon TypeScript SDK