sp-neon

name	sp-neon
description	Use for Neon provider guidance in this project.

Neon provider guidance

Generated by stripe projects llm-context for Neon. Source: https://neon.com/agentic-provisioning-llm-context.md

---

name: neon-provider-llm-context description: Context for agents using or developing the Agentic Provisioning Protocol (APP) with Neon. Covers where credentials come from (account request response), how to use the returned API key for the Neon API (projects, branches, connection strings), and provisioning resources. Use when the agent receives or uses APP credentials or implements APP flows.

Agentic provisioning with Neon

Neon is the backend for apps and agents. Neon Postgres, Neon Auth, and Data API are available today, with Storage, Compute, and AI Gateway coming soon. Every service is agent-ready: instant, branchable, and serverless.

Context for LLMs and agents: use the API key from the APP account request to interact with Neon (projects, branches, connection strings, provisioning). Full documentation index: neon.com/docs/llms.txt.

---

Part 1: APP credentials and Neon API

Where the API key comes from

In the APP flow, the orchestrator (e.g. Stripe) calls the provider (Neon) to create or link an account for the developer:

• Endpoint: POST <provider_base_url>/provisioning/account_requests
• Response (success): type: "credentials" with:
  • credentials.access_token — User-scoped API key (Bearer token). Use for all Neon API and APP provisioning calls for this user.
  • credentials.account.id — Account (user) identifier (use when the protocol or APIs require an account/user ID).

Response field	How the agent uses it
credentials.access_token	Send as Authorization: Bearer <access_token> on every Neon API request and on APP provisioning requests that act on this user (e.g. POST .../provisioning/resources).
credentials.account.id	Use when linking resources to the correct user or when the API requires an account ID.

Use the same API key for all operations in this document (projects, branches, connection URIs, provisioning resources).

How to use the API key

• Authentication: Authorization: Bearer <access_token> on every request.
• Neon API base URL: https://console.neon.tech/api/v2/

Example — list the user's projects:

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

(Replace $NEON_API_KEY with the access_token from the account request.)

Neon API operations (with the API key)

All of these use the same Authorization: Bearer <access_token> and base URL above.

A full list of endpoints, request/response schemas, rate limits, and constraints is in Neon REST API.

Create a branch — Optional body: branch.parent_id (omit to use project default branch), endpoints (e.g. [{ "type": "read_write" }] for compute). Example:

curl -X POST 'https://console.neon.tech/api/v2/projects/{project_id}/branches' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"endpoints":[{"type":"read_write"}],"branch":{}}'

Provisioning resources (APP) — When the orchestrator provisions a resource (POST .../provisioning/resources), it sends the same Bearer token so the provider knows which user account to create the resource for. The response may include access_configuration (e.g. connection_string, project_id, branch_id, or api_key and api_base_url). Use the returned details with the same API key for further operations.

---

Part 2: Neon documentation and features

Neon is the backend for apps and agents. Use the API key from Part 1 for all Neon API and connection operations. The Neon docs are the source of truth; prefer fetching current docs over relying on training data.

Fetching docs as Markdown: Append .md to the URL (e.g. https://neon.com/docs/introduction/branching.md) or send Accept: text/markdown on the standard URL.

Docs index (all pages): https://neon.com/docs/llms.txt — search here for a topic if not listed below.

Doc links by topic

Topic	Use when	Link
What Is Neon	Architecture, terminology (orgs, projects, branches, endpoints)	what-is-neon.md
Getting Started	First-time setup, connection strings, driver install, schema	getting-started.md
Connection Methods & Drivers	Choosing transport/driver (TCP, HTTP, WebSocket, edge, serverless)	connection-methods.md
Serverless Driver	@neondatabase/serverless, HTTP/WebSocket, runtime optimizations	neon-serverless.md
Neon JS SDK	Neon Auth + Data API, PostgREST-style queries, typed client	neon-js.md
Developer Tools	npx neonctl@latest init, VSCode, Neon MCP server	devtools.md
Neon CLI	Terminal/scripts/CI with neonctl	neon-cli.md
Neon REST API	Direct HTTP automation, API key auth, rate limits, polling	neon-rest-api.md
Neon TypeScript SDK	Typed Neon control in TypeScript (@neondatabase/api-client)	neon-typescript-sdk.md
Neon Python SDK	Programmatic Neon management in Python (neon-api)	neon-python-sdk.md
Neon Auth	Managed auth, UI components, methods, Next.js/React integration	neon-auth.md (see also Neon JS SDK)
Branching	Isolated environments, preview deployments, branch lifecycle	branching.md
Autoscaling	Compute scaling with workload, CU sizing	autoscaling.md
Scale to Zero	Idle suspend/resume, cold-start trade-offs	scale-to-zero.md
Instant Restore	Point-in-time recovery, branch from history, Time Travel	branch-restore.md
Read Replicas	Read-only compute, analytics/reporting	read-replicas.md
Connection Pooling	PgBouncer, -pooler hostnames, serverless concurrency	connection-pooling.md
IP Allow Lists	Restrict access by IP/CIDR	ip-allow.md
Logical Replication	CDC, external Postgres sync	logical-replication-guide.md

Key points (brief):

• Branching: Instant copy-on-write clones; each branch has its own compute endpoint.
• Scale to zero: Idle compute suspends (default 5 min); first query after suspend has cold-start penalty; storage stays active.
• Connection pooling: Add -pooler to endpoint hostnames for pooled connections; important in serverless.