NextPDF Connect — REST transport

At a glance

The Representational State Transfer (REST) transport runs bin/nextpdf-server in a RoadRunner Hypertext Transfer Protocol (HTTP) worker pool. An OpenAPI 3.1 document defines the surface. The transport authenticates every non-health request with a bearer application programming interface (API) key, and gates Pro and Enterprise routes by the installed tier.

Install

composer require nextpdf/server
./vendor/bin/rr get-binary

Conceptual overview

Each request passes through a PHP Standard Recommendation 15 (PSR-15) middleware pipeline before it reaches a handler: request-id assignment, body-size and tier-payload limits, Cross-Origin Resource Sharing (CORS), authentication, capability authorization, per-IP and per-client rate limiting, idempotency, and a timeout. A PSR-15 middleware that cannot produce the response itself delegates to the provided request handler (PSR-15 §2.2 MiddlewareInterface::process, clause psr_15_handlers#2.2.p14). The PHP Standard Recommendation 7 (PSR-7) request objects in the pipeline are immutable: a state-changing call returns a new instance instead of mutating the original (PSR-7 §3.2.1).

The route table is built at boot and depends on the runtime. Core routes are always registered. Pro operation routes register only when Pro or Enterprise is installed. Enterprise routes register only when Enterprise is installed. Session routes register only when sessions are enabled.

API surface

Always-registered routes

Method	Path	Auth
`GET`	`/healthz`	none (liveness)
`GET`	`/readyz`	none (readiness)
`POST`	`/api/v1/render`	bearer
`GET`	`/api/v1/capabilities`	bearer
`POST`	`/api/v1/jobs`	bearer
`GET`	`/api/v1/jobs/{id}`	bearer
`GET`	`/api/v1/jobs/{id}/result`	bearer
`DELETE`	`/api/v1/jobs/{id}`	bearer
`POST`	`/api/v1/extract-text` · `/merge` · `/split`	bearer

The health probes are safe, read-only endpoints. They cause no state change, which is the safe-method property defined by Request for Comments (RFC) 9110 (RFC 9110 §9.2.1).

Tier-gated routes (runtime-dependent)

NextPDF registers these routes only when the corresponding package is installed:

Pro or Enterprise installed: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
Enterprise installed: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

If the route’s tier is not installed, the route is not registered and the request is not routed. If the key is valid but its tier is below the route’s tier, the request is rejected with 403. Where signing is exposed, NextPDF Connect with Pro provides PDF Advanced Electronic Signatures (PAdES) baseline-B (B-B) signing only; long-term-validation profiles are not part of this transport’s surface.

OpenAPI contract

The REST surface ships as a static OpenAPI 3.1 document at openapi/nextpdf-connect.yaml in the package. It uses a bearer API key security scheme in the Authorization header (Bearer npk_live_{kid}_{secret}). Error responses use RFC 7807 problem-details documents with a type URL for each condition.

OpenAPI rendering — Scalar

Per the documentation platform plan §12, the aggregated documentation site renders this OpenAPI document with Scalar (@scalar/api-reference). The REST integration page embeds it as a <ScalarApiReference src=…> component. The package’s openapi/nextpdf-connect.yaml remains the source of truth. The site build pulls and renders that file instead of maintaining a parallel endpoint reference by hand. No runtime OpenAPI-serving endpoint is part of the server; the document is a build-time artifact.

Code sample — Quick start

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

Code sample — Production

Run the combined profile so the REST and gRPC transports share one supervisor:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
./vendor/bin/rr serve -c .rr.full.yaml

Edge cases and gotchas

A tier route returns 404 when the package is absent. The route is not registered, so the router does not match it. This is expected; it is not an authentication failure.
401 versus 403. 401 means the request has no valid key, and the response carries a WWW-Authenticate: Bearer header per RFC 9110 §11.6.1. 403 means the key is valid, but its tier is not entitled to the operation.
Sessions are off by default. The /api/v1/sessions/... routes exist only when NEXTPDF_SESSIONS_ENABLED=true and tools are available.
High-risk operations still gate. A REST call that drives an ApprovalRequired tool passes through the same human-in-the-loop gate as the Model Context Protocol (MCP). See /connect/hitl-risk-tiers/.

Performance

Each RoadRunner worker handles one request at a time. Long synchronous renders hold a worker. Use the async job routes for slow work so workers are freed. Size the pool against observed latency; see /connect/production-usage/.

Security notes

Terminate Transport Layer Security (TLS) in front of the REST listener. The listener binds plaintext HTTP by design and expects an upstream terminator. Authenticate with a sufficiently random npk_live_ key, store keys outside source control, and prefer the hot-reloading file key store. See /connect/security-and-operations/.

Conformance

Claim	Source	`reference_id`
`401` MUST carry a `WWW-Authenticate` challenge	RFC 9110 §11.6.1
Safe methods are read-only	RFC 9110 §9.2.1
PSR-7 requests are immutable	PSR-7 §3.2.1
Middleware unable to produce the response delegates to the provided request handler	PSR-15 §2.2 `MiddlewareInterface::process` (`psr_15_handlers#2.2.p14`)

Commercial context

Signing, redaction, comparison, accessibility, optimization, and compliance routes appear only when nextpdf/premium is installed. The authentication model remains unchanged; the key’s tier determines access.