canonical: https://jentic.com/apis/neon.tech/neon-tech

# Neon Tech Neon API

The Neon API on the neon.tech control-plane host is the management interface for Neon, the serverless Postgres platform with database branching. The 138 endpoints cover projects, branches, compute endpoints, databases, roles, operations, API keys, and the advisor and shared-projects features. Teams use it to spin up Postgres branches in seconds, attach read-replica endpoints, and automate copy-on-write previews for every pull request.

## For AI agents

Manage Neon Postgres projects, branches, compute endpoints, roles, and API keys via the neon.tech control plane.

## Scope

Does not handle direct SQL execution, row-level reads, or schema migrations - use for Neon platform management of projects, branches, and compute endpoints only.

## Capabilities

- Provision and destroy Neon projects with regions and Postgres versions chosen at create time
- Create branches off any project for preview environments, restore from a point in time, or fork production data
- Spin up compute endpoints (read-write and read replicas) attached to a branch
- Create roles and databases inside a branch, and rotate role passwords
- Mint and revoke scoped API keys for service accounts and CI runners
- Track long-running operations and inspect advisor findings on each project

## Use cases

### Per Pull Request Database Branches

Engineering teams script `/projects/{project_id}/branches` so every pull request gets its own isolated Postgres branch off the production schema and data. The branch is a copy-on-write fork - provisioning takes seconds, the preview environment runs migrations against real data, and the branch is deleted when the PR closes.

Example prompt: Create a branch named pr-1234 off the main branch of project shadowy-snow-12345, then return the connection string for the new compute endpoint.

### Read Replica Provisioning

Backend services attach a read-replica compute endpoint to a branch to scale BI and analytics reads without slowing the write path. Replicas spin up in seconds and scale to zero when idle, so the cost matches actual query traffic rather than peak provisioned capacity.

Example prompt: Create a read-replica compute endpoint on the main branch of a Neon project and return its connection string for the BI dashboard.

### Restore from Point in Time

Operations engineers respond to a bad migration by calling `/projects/{project_id}/restore` against a recent timestamp. Neon resolves the request to a fresh branch at that data state, and `/projects/{project_id}/operations/{operation_id}` reports progress until the branch is ready.

Example prompt: Restore the main branch of a Neon project to its state from 2 hours ago and poll the operation until it reports finished.

### AI Agent Integration via Jentic

An AI agent uses Jentic to provision Neon resources during a deploy or test workflow. Jentic exposes /projects, /branches, and /endpoints by intent, the agent supplies project, region, and Postgres version, and the bearer key stays in your Jentic One instance rather than the agent context.

Example prompt: Use Jentic to search for create a neon project, load the schema, and create a project named agent-demo in the us-east-2 region.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/projects` | List Neon projects |
| POST | `/projects` | Create a new Neon project |
| GET | `/projects/{project_id}` | Get a project by id |
| POST | `/projects/{project_id}/restore` | Restore a branch to a point in time |
| GET | `/projects/{project_id}/operations/{operation_id}` | Get operation status |
| GET | `/api_keys` | List API keys |
| POST | `/api_keys` | Mint an API key |
| DELETE | `/api_keys/{key_id}` | Revoke an API key |

## Key resources

- **Projects** — Create, list, update, and delete Neon projects
- **Branches** — Create branches, restore to a point in time, and manage branch settings
- **Compute Endpoints** — Create read-write and read-replica endpoints on a branch
- **Databases and Roles** — Manage Postgres databases and roles inside a branch
- **API Keys** — Mint and revoke API keys for service accounts
- **Operations** — Track long-running asynchronous operations

## Why Jentic

- **Setup:** Wiring the Neon API by hand means passing the bearer key on every request, polling the operations endpoint until asynchronous project and branch actions settle, and managing your own API keys through the console host yourself. Through Jentic you install once, import Neon from the API Directory, store the bearer key once, and your agent calls it.
- **Permission scoping:** Neon puts the project id in the URL path (`/projects/{project_id}/...`), so a rule can pin your agent to one project: it can read that project and its operations and nothing else. You choose the operations it may call, so project restore or API key deletion is not included unless you add it.
- **Credential handling:** Your Neon bearer key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Neon branch' or 'check a project operation status', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Supabase API** — Postgres-based backend platform with auth, storage, and edge functions
- **PlanetScale API** — Serverless MySQL platform with database branching
- **Vercel API** — Frontend cloud that often pairs a Neon branch with each Vercel preview deploy
- **Cockroach Cloud API** — Distributed SQL database compatible with the Postgres wire protocol

## FAQ

### What authentication does the Neon API use?

The Neon API uses bearer tokens (BearerAuth in the spec). Mint a key in the Neon console or via /api_keys, store it in your Jentic One instance, and pass it as Authorization: Bearer in every request. Cookie auth is also supported for the web console but not for programmatic clients.

### Can I create a database branch with the Neon API?

Yes. POST to the branches endpoint under `/projects/{project_id}` with a parent_id and an optional point-in-time. Neon returns the new branch immediately and a compute endpoint can be attached for read-write access.

### How do I provision a Neon project through Jentic?

Search Jentic for create a neon project, load the schema for POST /projects, then execute with the project name, region, and Postgres version. The full flow is pip install jentic, search, load, execute.

### What are the rate limits for the Neon API?

Neon enforces account-level concurrency and rate limits that vary by plan. The spec does not include numeric per-second caps, so treat heavy automation as bursty and back off on 429s. Long-running actions return an operation id under `/projects/{project_id}/operations.`

### Can I restore a Neon branch to a previous point in time?

Yes. POST `/projects/{project_id}/restore` with the source branch and a timestamp inside the project history retention window. Neon creates a new branch at that state and returns an operation id for status tracking.

### How do I mint a Neon API key for a CI runner?

POST /api_keys with a name. Neon returns the key once, in the response body - store it in your Jentic One instance immediately. List existing keys with GET /api_keys and revoke with DELETE `/api_keys/{key_id}.`

### Can I limit what my agent is allowed to do with the Neon API?

Yes. Neon puts the project id in the URL path, so a rule in your self-hosted Jentic One instance can pin your agent to a single project and let it read only that project and its operations. You decide which operations the agent may call, so destructive actions like POST `/projects/{project_id}/restore` or DELETE `/api_keys/{key_id}` stay off limits unless you add them. Because the rules and the stored bearer key live in your own instance, the operator, not the agent, controls the scope of what it can touch.