Connect REST API reference

At a glance

NextPDF Connect exposes its tool registry over HTTP as a REST transport, described by an OpenAPI 3.1 contract. This page is the reference for that surface: the base URL, how to authenticate, the operation groups, and the error model. The full machine-readable specification is published so you can load it into an interactive explorer, a client generator, or a request client without copying anything by hand.

For the transport-independent tool catalog (the same operations over the Model Context Protocol and gRPC as well as REST), see the Connect API reference. For the RoadRunner pipeline, deployment, and authentication setup, see the REST transport guide.

Base URL and authentication

The REST transport listens on the host and port configured for your deployment. In a local run that is http://localhost:8080; in production it is the address in front of your worker pool.

Authentication is a bearer token. Send the API key in the Authorization header on every request to a tier-gated route:

curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

Read-only liveness and readiness probes do not require a token.

Operations

Availability is tier-gated. The open-source core ships the document, render, session, and job operations. Signing, form filling, redaction, comparison, accessibility checking, and optimization require a commercial edition installed alongside the server. The authoritative set for a given deployment is returned by the capabilities endpoint. Query it rather than assuming a fixed list.

Health and lifecycle

Method	Path	Purpose
GET	/healthz	Liveness probe. No authentication.
GET	/readyz	Readiness probe (dependencies and worker pool ready). No authentication.
GET	/api/v1/capabilities	The tools and tiers this deployment actually exposes. Query this first.

Rendering and documents

Method	Path	Purpose
POST	/api/v1/render	Render a document from an ordered list of operations and return the PDF.
POST	/api/v1/extract-text	Extract text content from a PDF.
POST	/api/v1/merge	Merge several PDF inputs into one document.
POST	/api/v1/split	Split a PDF into multiple documents.

Asynchronous jobs

Method	Path	Purpose
POST	/api/v1/jobs	Submit a long-running operation as a job.
GET	/api/v1/jobs/{id}	Poll job status.
GET	/api/v1/jobs/{id}/result	Retrieve the completed job result.

Sessions

Sessions hold a document open across several calls so you build it incrementally and render once at the end.

Method	Path	Purpose
POST	/api/v1/sessions	Open a session.
GET / DELETE	/api/v1/sessions/{sessionId}	Inspect or close a session.
POST	/api/v1/sessions/{sessionId}/pages	Add a page.
POST	/api/v1/sessions/{sessionId}/text	Add text.
POST	/api/v1/sessions/{sessionId}/images	Add an image.
POST	/api/v1/sessions/{sessionId}/tables	Add a table.
POST	/api/v1/sessions/{sessionId}/html	Add rendered HTML.
POST	/api/v1/sessions/{sessionId}/font	Set the active font.
POST	/api/v1/sessions/{sessionId}/render	Render the session document.

Commercial-edition operations

These routes register only when the matching commercial edition is installed. Several are approval-gated by the human-in-the-loop confirmation flow; see risk tiers.

Method	Path	Purpose
POST	/api/v1/sign	Apply a digital signature.
POST	/api/v1/fill-form	Fill an interactive form.
POST	/api/v1/redact	Redact content.
POST	/api/v1/compare	Compare two PDF documents.
POST	/api/v1/check-accessibility	Run a structural accessibility check.
POST	/api/v1/optimize	Optimize and reduce a document.

Error model

The REST transport uses HTTP status codes with the semantics defined by RFC 9110: 2xx for success, 4xx for a request the caller must fix (400 malformed body, 401 missing or invalid token, 403 tier or approval denied, 404 unknown route or job, 409 idempotency conflict, 422 a well-formed request the engine cannot process), and 5xx for a server-side failure. A 401 response carries a WWW-Authenticate challenge.

Error bodies are application/problem+json documents per RFC 9457 (Problem Details for HTTP APIs): a stable type, a short title, the numeric status, and a human-readable detail. Match on type, not on the detail string. See also RFC 9110 (HTTP Semantics) and RFC 9457 for the normative definitions.

Submit state-changing requests with an Idempotency-Key header so a retried request is processed once.

Machine-readable specification

The full contract is published as a static OpenAPI 3.1 document:

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

Use it as the single source of truth for the REST surface:

1. Open the interactive API explorer — an in-browser, self-hosted Scalar reference generated from this contract — to read and try every operation with its request and response schemas.
2. Import it into a request client such as Postman or Insomnia.
3. Generate a typed client for your language with an OpenAPI generator.

The document is a static contract, version-pinned to the package. It is not served by a live endpoint, so it stays stable across deployments.

See also

• Connect API reference — the full tool catalog across MCP, REST, and gRPC.
• REST transport guide — RoadRunner pipeline, bearer auth, and tier routing.
• NextPDF Connect overview — what the server is and how to run it.