Neon API

The Neon API allows you to manage your Neon projects programmatically. You can create and manage projects, branches, databases, roles, compute endpoints, and more — everything you can do in the Neon Console, you can do with the API.

Quick links

• Neon API Reference — Interactive API documentation with "Try It" feature
• OpenAPI Specification — Machine-readable API spec (OpenAPI 3.0)
• Neon SDKs — TypeScript and Python SDKs for the Neon API

Getting started

Prerequisites

Before using the Neon API, you need:

1. A Neon account — Sign up if you don't have one
2. An API key — Create one in the Neon Console (see below)
3. curl or an HTTP client — Or use our TypeScript or Python SDKs

API key types

Neon supports three types of API keys, each with different scopes:

Create your first API key in the Neon Console under Account settings > API keys. For detailed instructions, see Manage API keys.

Base URL

All API requests use this base URL:

https://console.neon.tech/api/v2/

Authentication

Include your API key in the Authorization header using Bearer authentication:

curl 'https://console.neon.tech/api/v2/projects' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"

Make your first API call

Set your API key as an environment variable, then list your projects:

# Set your API key
export NEON_API_KEY="your-api-key-here"

# List all projects
curl 'https://console.neon.tech/api/v2/projects' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq

The response includes your projects with their IDs, regions, and other details:

{
  "projects": [
    {
      "id": "spring-example-302709",
      "name": "my-project",
      "region_id": "aws-us-east-2",
      "pg_version": 17,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Use the project_id from the response to make subsequent requests, such as creating a branch:

curl -X POST 'https://console.neon.tech/api/v2/projects/spring-example-302709/branches' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"branch": {"name": "dev-branch"}}'

Key concepts

Asynchronous operations

Many Neon API operations (creating branches, starting computes, etc.) are asynchronous. The API response includes an operations array with status information:

"operations": [
  {
    "id": "22acbb37-209b-4b90-a39c-8460090e1329",
    "action": "create_branch",
    "status": "running"
  }
]

Status values: scheduling, running, finished, failed, cancelling, cancelled, skipped

When building automation, poll the operation status before proceeding with dependent requests:

curl 'https://console.neon.tech/api/v2/projects/{project_id}/operations/{operation_id}' \
  -H "Authorization: Bearer $NEON_API_KEY"

For details, see Poll operation status.

Rate limiting

• 700 requests per minute (approximately 11 per second)
• 40 requests per second burst limit per route

Exceeding these limits returns HTTP 429 Too Many Requests. Implement retry logic with exponential backoff in your applications.

Pagination

Some endpoints that return lists support cursor-based pagination. Include limit and cursor parameters:

# First request with limit
curl 'https://console.neon.tech/api/v2/projects?limit=10' ...

# Subsequent request with cursor from previous response
curl 'https://console.neon.tech/api/v2/projects?limit=10&cursor=...' ...

SDKs and tools

Instead of using curl, you can use our official SDKs:

• TypeScript SDK — Full-featured SDK for Node.js and browser
• Python SDK — Pythonic wrapper for the Neon API
• @neondatabase/toolkit — Combined SDK for AI agents (includes API SDK + Serverless Driver)
• Neon CLI — Command-line interface for Neon

See Neon SDKs for the full list, including community SDKs.

API reference documentation

The interactive Neon API reference provides:

• Complete endpoint documentation
• Request/response examples
• "Try It" feature to execute requests directly
• Schema definitions for all objects

You can also access the OpenAPI specification directly for code generation or API tooling.

API examples index

The following sections link to API examples and guides throughout the Neon documentation, organized by resource type and use case.

Core resources

Manage the fundamental building blocks of your Neon account.

• Manage API keys — Create, list, and revoke API keys for personal accounts and organizations
• Manage projects — Create, list, update, delete, and recover projects
• Manage branches — Create, list, and delete branches
• Manage computes — Create, configure, restart, and delete compute endpoints
• Manage roles — Create roles, reset passwords, and manage database access
• Manage databases — Create, list, update, and delete databases
• View operations — List operations, check status, and poll for completion
• Maintenance windows — Configure maintenance windows for compute updates via API
• Organizations API — Manage organization members and permissions
• Project transfer — Transfer projects between accounts and organizations

Usage and billing

Monitor resource consumption and configure usage limits.

• Monitor usage metrics — Retrieve usage data for projects and branches
• Query consumption metrics — Query account-level and project-level consumption history
• Organization consumption — Query usage metrics for organizations
• Configure consumption limits — Set and update quotas on compute, storage, and data transfer

Branching workflows

Work with branches programmatically for development, testing, and CI/CD.

• Branching with the Neon API — Comprehensive guide to branch management via API
• Branch restore — Restore branches to a previous state using Time Travel
• Branch expiration — Automatically delete branches after a specified time
• Schema-only branches — Create branches with schema but no data
• Reset from parent — Reset a branch to match its parent's current state
• Protected branches — Configure IP allowlist restrictions for protected branches
• Branching for testing — Create isolated branches for running test queries
• Branch archiving — Monitor branch archive status via API

Snapshots and backup

Create and manage point-in-time snapshots for backup and versioning.

• Backup and restore — Create scheduled and on-demand snapshots
• Database versioning — Create and manage snapshots via API for version control

Data management

Transform and compare data across branches.

• Data anonymization API — Create anonymized copies of production data with masking rules
• Data anonymization workflow — End-to-end guide for setting up data anonymization
• Schema comparison — Compare schemas between branches via API
• Schema diff tutorial — Step-by-step schema comparison guide with API example

Read replicas

Scale read operations with dedicated read-only compute endpoints.

• Read replicas overview — List and manage read replica endpoints
• Create read replicas — Create, configure, and delete read replica computes
• Read replicas for data analysis — Create read replicas for analytics workloads
• Read replicas for ad-hoc queries — Create read replicas for exploratory queries

Security and compliance

Configure security features and compliance settings.

• HIPAA compliance — Create and configure HIPAA-compliant projects via API
• API key management — Secure API key handling for personal and organization accounts