API

The Neon services expose several distinct API surfaces. This section is a guided tour of the public ones, with pointers to the OpenAPI specs and protobuf definitions where applicable.

Surfaces

Service	Surface	Pages
Pageserver	libpq GetPage@LSN, gRPC page API, HTTP management	Pageserver API
Safekeeper	libpq replication (compute → SK and SK → PS), HTTP management	Safekeeper API
Storage controller	HTTP (/v1/, /control/v1/, /debug/v1/, /upcall/v1/)	Storage controller API
Storage broker	gRPC pub/sub	covered in Storage broker
compute_ctl	HTTP control + Prometheus metrics	covered in compute_ctl
Endpoint storage	HTTP CRUD	covered in Endpoint storage
Proxy	libpq + WebSockets + SQL/HTTP	Proxy HTTP API

Where to find specs

The OpenAPI sources are checked in next to the code:

File	Service
pageserver/src/http/openapi_spec.yml	Pageserver HTTP management API
safekeeper/src/http/openapi.yaml	Safekeeper HTTP management
compute_tools/src/openapi_spec.yml	compute_ctl HTTP API
endpoint_storage/src/openapi_spec.yml	Endpoint storage HTTP

make lint-openapi-spec runs Redocly over all of them.

For gRPC:

File	Service
storage_broker/proto/broker.proto	Storage broker pub/sub
pageserver/page_api/proto/	Pageserver page API (gRPC variant of GetPage@LSN)

For libpq replication-stream protocols, the wire format is documented in docs/safekeeper-protocol.md for the safekeeper and inline in pageserver/src/page_service.rs for the pageserver.

Authentication

All Neon HTTP and replication APIs use the same JWT scheme:

• Tokens are signed with an asymmetric key pair (RS256/Ed25519).
• Each token has a scope claim — the scopes used today include pageserverapi, tenant, safekeeperdata, and a few more.
• The relevant verification code is in libs/utils/src/auth.rs.

The proxy talks to the pageserver / compute on behalf of the user, but the user-facing authentication (against the proxy) uses Postgres SCRAM-SHA-256, not JWTs. JWTs only show up between Neon services.

Stability notes

• The HTTP surfaces are versioned (/v1/, /control/v1/, …). Breaking changes go through a new version path.
• The libpq protocols are stable in the sense that they reuse Postgres's stable replication-stream framing. The semantics of the message payloads (e.g. the PagestreamGetPage opcode set) evolve more freely; the pageserver client / server negotiate protocol features at handshake time.
• The gRPC page API is newer and considered evolving. The protobuf is in pageserver/page_api/proto/.

Internal APIs that are not on this list

The following are internal protocols not intended for external consumption:

• The deletion-queue protocol used by the pageserver to safely batch S3 deletions (pageserver/src/deletion_queue.rs).
• The compute_hook protocol used by the storage controller to notify computes (storage_controller/src/compute_hook.rs).
• The reconciler's per-pageserver HTTP traffic (the same as the pageserver management API but with different scopes).

These are exercised by tests but should not be relied on by external code.

See also

• Patterns and conventions — how axum/tonic are used.
• Authentication — JWT setup and SCRAM specifics.