Create Neon Data API

Creates a new instance of Neon Data API in the specified branch.

POST /projects/{project_id}/branches/{branch_id}/data-api/{database_name}

Creates a new instance of Neon Data API in the specified branch. The Data API exposes a REST interface over the branch database. The database_name path parameter determines which database the API serves.

Markdown for AI context

REST API - curl

curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/data-api/$DATABASE_NAME" \
  -X POST \
  -H "Authorization: Bearer $NEON_API_KEY"

Every field below is optional. An empty body works too.

Also available in

Bash

neon data-api create

Tool: provision_neon_data_api

Provisions the Neon Data API for a Neon branch. The Data API enables HTTP-based access to your Postgres database with automatic JWT authentication support. When called WITHOUT an authProvider: 1. Automatically checks if Neon Auth is already provisioned 2. Checks if Data API already exists 3. Returns authentication options for user selection: - neon_auth: Use Neon Auth (recommended) - external: Use external provider (Clerk, Auth0, Stytch) - none: No authentication (not recommended) 4. User selects an option, then call this tool again with authProvider specified When called WITH authProvider="neon_auth" and provisionNeonAuthFirst=true: - Automatically provisions Neon Auth first (if not already set up) - Then provisions the Data API with Neon Auth integration When called WITH authProvider="none": - Provisions Data API without a pre-configured JWKS - User will need to manually configure a JWKS URL before the Data API can be used The tool will: 1. Resolve the default branch if branchId is not provided 2. Resolve the default database if databaseName is not provided 3. If no authProvider: check existing config and return options for selection 4. If authProvider specified: create the Data API endpoint with that auth 5. If provisionNeonAuthFirst: set up Neon Auth before Data API 6. Return the Data API URL for your application - HTTP-based API: Access your Postgres database via REST endpoints - JWT Authentication: Supports Neon Auth or external providers (Clerk, Auth0, Stytch, etc.) - Row Level Security: Works with RLS policies for fine-grained access control - Branch-compatible: Data API configuration branches with your database - PostgREST-compatible: Uses the same API patterns as PostgREST

projectId (string, required) The ID of the project to provision the Data API for
branchId (string, optional) An optional ID of the branch to provision the Data API for. If not provided, the default branch is used.
databaseName (string, optional) The database name to provision the Data API for. If not provided, the default database is used.
authProvider (enum, optional) The authentication provider - "neon_auth" for Neon Auth integration, "external" for third-party providers like Clerk, Auth0, or Stytch, or "none" for unauthenticated access (not recommended). If not specified, the tool will check existing auth configuration and return options for selection.
jwksUrl (string, optional) The JWKS URL for external authentication providers. Required when authProvider is "external".
providerName (string, optional) The name of the external authentication provider (e.g., "Clerk", "Auth0", "Stytch"). Used when authProvider is "external".
jwtAudience (string, optional) The expected JWT audience claim. Tokens without an audience claim will still be accepted.
provisionNeonAuthFirst (boolean, optional) When true with authProvider="neon_auth", provisions Neon Auth before Data API if not already set up.

Console path: Projects → Data API

Parameters

Project ID

project_id

string

The Neon project ID

Branch ID

branch_id

string

The Neon branch ID

Database name

database_name

string

The database name

Request body

No field is required. Send an empty body to use sensible defaults.

Auth provider

auth_provider

string

Authentication provider for the Neon Data API. neon_auth: use Neon's built-in managed authentication (no JWKS configuration required). external: use an external JWT provider, which requires jwks_url. When omitted, no auth provider is configured (existing setup is kept).

neon_authexternal

JWKS url

jwks_url

string

URL of the JWKS endpoint used to verify JWTs for this Data API. Required when configuring JWT-based authentication; omit when using a non-JWT auth provider.

Provider name

provider_name

string

Display name for the authentication provider. Accepted values include "Clerk", "Stytch", and "Auth0", but any non-empty string is valid. Optional field.

JWT audience

jwt_audience

string

Expected aud claim in incoming JWTs. When set, tokens with a different audience are rejected; tokens with no audience are still accepted. Omit to skip audience validation.

Add default grants

add_default_grants

booleandefault: false

Grant all permissions to the tables in the public schema to authenticated users

Skip auth schema

skip_auth_schema

booleandefault: false

Skip creating the auth schema and RLS functions

Settings

settings

object

Auth and schema configuration for the Data API.

Response

201

Creates a new app

Depth

"url": (string),requri

Errors

default

General error

This endpoint can return the standard Neon API error response.

Response fields

message Required. Human-readable error message.
code Required. Machine-readable error code.
request_id Optional. Request identifier for debugging. You can provide one with the X-Request-ID header.

Retry guidance

If no response is returned, the request may still have reached the server. This is why retry safety depends on the method and status code.

Idempotent methods (GET, HEAD, OPTIONS) are generally safe to retry after a network error or timeout. Non-idempotent methods (POST, PATCH, DELETE, PUT) can change state, so avoid automatic retries unless your workflow can tolerate duplicate effects.

Responses with 423 Locked or 503 Service Unavailable are safe to retry. 423 Locked means the resource is temporarily locked, usually because another operation is in progress.