---
title: Neon API
enableTableOfContents: true
redirectFrom:
  - /docs/reference/about
  - /docs/api/about
updatedOn: '2026-02-01T13:37:13.532Z'
---

<CopyPrompt src="/prompts/neon-api-prompt.md" title="AI prompt: Get started with the Neon API"
description="Copy this prompt into your AI coding assistant (Cursor, Copilot, etc.) to get help creating your first API key and making your first successful API call — using curl, the TypeScript SDK, or the Python SDK."/>

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](https://api-docs.neon.tech/reference/getting-started-with-neon-api) — Interactive API documentation with "Try It" feature
- [OpenAPI Specification](https://neon.com/api_spec/release/v2.json) — Machine-readable API spec (OpenAPI 3.0)
- [Neon SDKs](/docs/reference/sdk) — TypeScript and Python SDKs for the Neon API

## Getting started

### Prerequisites

Before using the Neon API, you need:

1. **A Neon account** — [Sign up](https://console.neon.tech/signup) 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](/docs/reference/typescript-sdk) or [Python](/docs/reference/python-sdk) SDKs

### API key types

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

| Key Type                   | Scope                                  | Best For                      |
| -------------------------- | -------------------------------------- | ----------------------------- |
| **Personal API Key**       | All projects you own or have access to | Personal development, scripts |
| **Organization API Key**   | All projects within an organization    | Team automation, CI/CD        |
| **Project-scoped API Key** | Single project only                    | Limited access integrations   |

Create your first API key in the Neon Console under **Account settings** > **API keys**. For detailed instructions, see [Manage API keys](/docs/manage/api-keys).

<Admonition type="important">
API key tokens are shown only once at creation. Store them securely — you cannot retrieve them later.
</Admonition>

### Base URL

All API requests use this base URL:

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

### Authentication

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

```bash
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:

<Tabs labels={["curl", "TypeScript SDK", "Python SDK"]}>

<TabItem>

```bash
# 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
```

</TabItem>

<TabItem>

```bash
npm install @neondatabase/api-client
```

```typescript
import { createApiClient } from '@neondatabase/api-client';

const apiClient = createApiClient({
  apiKey: process.env.NEON_API_KEY!,
});

async function listProjects() {
  const response = await apiClient.listProjects({});
  console.log(response.data.projects);
}

listProjects();
```

</TabItem>

<TabItem>

```bash
pip install neon-api
```

```python
import os
from neon_api import NeonAPI

neon = NeonAPI(api_key=os.environ["NEON_API_KEY"])

projects = neon.projects()
print(projects)
```

</TabItem>

</Tabs>

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

```json
{
  "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:

<Tabs labels={["curl", "TypeScript SDK", "Python SDK"]}>

<TabItem>

```bash
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"}}'
```

</TabItem>

<TabItem>

```typescript
const response = await apiClient.createProjectBranch('spring-example-302709', {
  branch: { name: 'dev-branch' },
});
console.log(response.data.branch);
```

</TabItem>

<TabItem>

```python
branch = neon.branch_create(
    project_id="spring-example-302709",
    branch={"name": "dev-branch"}
)
print(branch)
```

</TabItem>

</Tabs>

## 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:

```json
"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:

```bash
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](/docs/manage/operations#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:

```bash
# 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](/docs/reference/typescript-sdk)** — Full-featured SDK for Node.js and browser
- **[Python SDK](/docs/reference/python-sdk)** — Pythonic wrapper for the Neon API
- **[@neondatabase/toolkit](/docs/reference/neondatabase-toolkit)** — Combined SDK for AI agents (includes API SDK + Serverless Driver)
- **[Neon CLI](/docs/reference/neon-cli)** — Command-line interface for Neon

See [Neon SDKs](/docs/reference/sdk) for the full list, including community SDKs.

## API reference documentation

The interactive [Neon API reference](https://api-docs.neon.tech/reference/getting-started-with-neon-api) 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](https://neon.com/api_spec/release/v2.json) 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](/docs/manage/api-keys#manage-api-keys-with-the-neon-api) — Create, list, and revoke API keys for personal accounts and organizations
- [Manage projects](/docs/manage/projects#manage-projects-with-the-neon-api) — Create, list, update, delete, and recover projects
- [Manage branches](/docs/manage/branches#branching-with-the-neon-api) — Create, list, and delete branches
- [Manage computes](/docs/manage/computes#manage-computes-with-the-neon-api) — Create, configure, restart, and delete compute endpoints
- [Manage roles](/docs/manage/roles#manage-roles-with-the-neon-api) — Create roles, reset passwords, and manage database access
- [Manage databases](/docs/manage/databases#manage-databases-with-the-neon-api) — Create, list, update, and delete databases
- [View operations](/docs/manage/operations#operations-and-the-neon-api) — List operations, check status, and poll for completion
- [Maintenance windows](/docs/manage/updates#updates-on-paid-plans) — Configure maintenance windows for compute updates via API
- [Organizations API](/docs/manage/orgs-api) — Manage organization members and permissions
- [Project transfer](/docs/manage/orgs-project-transfer#transfer-projects-with-the-api) — Transfer projects between accounts and organizations

### Usage and billing

Monitor resource consumption and configure usage limits.

- [Monitor usage metrics](/docs/introduction/monitor-usage#retrieve-usage-metrics-with-the-neon-api) — Retrieve usage data for projects and branches
- [Query consumption metrics](/docs/guides/consumption-metrics#get-account-level-aggregated-metrics) — Query account-level and project-level consumption history
- [Organization consumption](/docs/manage/orgs-api-consumption#account-level-metrics) — Query usage metrics for organizations
- [Configure consumption limits](/docs/guides/consumption-limits#configuring-quotas) — 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](/docs/guides/branching-neon-api) — Comprehensive guide to branch management via API
- [Branch restore](/docs/introduction/branch-restore#how-to-use-instant-restore) — Restore branches to a previous state using Time Travel
- [Branch expiration](/docs/guides/branch-expiration#creating-a-branch-with-expiration) — Automatically delete branches after a specified time
- [Schema-only branches](/docs/guides/branching-schema-only#creating-schema-only-branches) — Create branches with schema but no data
- [Reset from parent](/docs/guides/reset-from-parent#how-to-reset-from-parent) — Reset a branch to match its parent's current state
- [Protected branches](/docs/guides/protected-branches#define-an-ip-allowlist-for-your-project) — Configure IP allowlist restrictions for protected branches
- [Branching for testing](/docs/guides/branching-test-queries#create-a-test-branch) — Create isolated branches for running test queries
- [Branch archiving](/docs/guides/branch-archiving#monitoring-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](/docs/guides/backup-restore#create-snapshots-manually) — Create scheduled and on-demand snapshots
- [Database versioning](/docs/ai/ai-database-versioning#creating-snapshots) — Create and manage snapshots via API for version control

### Data management

Transform and compare data across branches.

- [Data anonymization API](/docs/workflows/data-anonymization-api#create-anonymized-branch) — Create anonymized copies of production data with masking rules
- [Data anonymization workflow](/docs/workflows/data-anonymization#create-a-branch-with-anonymized-data) — End-to-end guide for setting up data anonymization
- [Schema comparison](/docs/guides/schema-diff#using-the-neon-api) — Compare schemas between branches via API
- [Schema diff tutorial](/docs/guides/schema-diff-tutorial#view-the-schema-differences) — Step-by-step schema comparison guide with API example

### Read replicas

Scale read operations with dedicated read-only compute endpoints.

- [Read replicas overview](/docs/introduction/read-replicas#manage-read-replicas-using-the-neon-api) — List and manage read replica endpoints
- [Create read replicas](/docs/guides/read-replica-guide#create-a-read-replica-using-the-api) — Create, configure, and delete read replica computes
- [Read replicas for data analysis](/docs/guides/read-replica-data-analysis#create-a-read-replica) — Create read replicas for analytics workloads
- [Read replicas for ad-hoc queries](/docs/guides/read-replica-adhoc-queries#setting-up-a-read-replica-for-ad-hoc-queries) — Create read replicas for exploratory queries

### Security and compliance

Configure security features and compliance settings.

- [HIPAA compliance](/docs/security/hipaa#step-2-enable-hipaa-for-your-projects) — Create and configure HIPAA-compliant projects via API
- [API key management](/docs/manage/api-keys) — Secure API key handling for personal and organization accounts

<NeedHelp/>