NextPDF Connect API reference

At a glance

This page is the symbol-level reference for the NextPDF Connect server (nextpdf/server). It lists each tool by registered tool name and implementing class, and documents the gRPC service NextPDFConnect, including its Remote Procedure Call (RPC) methods and request and response messages. It also defines the authentication, error, and rate-limit contract shared by every transport.

The server exposes one tool registry over three transports: Model Context Protocol (MCP) over standard input and output, a Representational State Transfer (REST) Application Programming Interface (API), and gRPC. Each transport documents its wire details on a separate page: see MCP transport, REST transport, and gRPC transport. This page catalogs the symbols those transports carry.

Tool names, classes, and risk tiers are read from the tool implementations in src/Tools/. The number of tools exposed by a deployment is a runtime property; see Tool catalog. Boot and discovery explains tier resolution.

Transport availability

A tool is available through each transport the deployment runs. Transports run as independent processes; starting one does not start the others.

Transport	Entry point	Wire format	Authentication
MCP	`bin/nextpdf-mcp`	JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 over stdio	Operating-system process boundary (no API key)
REST	`bin/nextpdf-server`	HTTP, OpenAPI 3.1	Bearer API key in the `Authorization` header
gRPC	`bin/nextpdf-grpc`	Protocol Buffers, package `nextpdf.connect.v1`	Bearer token in the `authorization` call metadata

Over MCP, you call a tool with tools/call and the registered tool name. Over REST and gRPC, you reach the same engine capabilities through the render, operation, and capability surfaces; see the REST transport route table and the gRPC transport RPC table.

Authentication and risk tier

API key authentication

The REST and gRPC transports require a bearer API key on every request except unauthenticated health probes. A key has the form npk_live_{kid}_{secret}: the kid is an eight-character identifier for record lookup, and the secret carries the entropy. The server stores only a SHA-256 digest of the key and compares the presented token in constant time, so an invalid key reveals nothing through timing. REST reads the token from the Authorization: Bearer … header; gRPC reads the same token from the authorization call metadata. The MCP stdio transport has no API key because it is a local subprocess trusted by its launching client. Security and operations documents the full authentication model.

The four risk tiers

Each tool declares one of four ordered risk levels, defined by the RiskLevel enum in src/Config/RiskLevel.php.

Tier	Enum case	Value	Effect
Safe	`RiskLevel::Safe`	0	Read-only, no side effects. Auto-executes.
Caution	`RiskLevel::Caution`	1	Creates or modifies in-memory state. Auto-executes, audit-logged.
Review	`RiskLevel::Review`	2	Produces output that could be misused. Auto-executes, audit-logged.
ApprovalRequired	`RiskLevel::ApprovalRequired`	3	Destructive, legal, or privacy-critical. Requires human confirmation.

A tool’s effective risk comes from exactly two places: the tool’s own riskLevel() declaration, and an optional operator configuration override that may only raise risk, never lower an ApprovalRequired tool. See HITL risk tiers and Configuration.

How approval tokens flow

When you invoke an ApprovalRequired tool without a valid token, the ConfirmationGate (src/Mcp/ConfirmationGate.php) returns a single-use challenge token instead of running the tool. The agent relays the challenge to a human, then re-invokes the same tool with the issued token in the _confirmation_token argument. The token binds the tool name, a random nonce, and a 300-second time-to-live (TTL). It does not bind the arguments and is not an authentication credential. On REST, the bearer API key still authenticates the request, and the same gate runs in the shared tool executor before the gated operation. On gRPC, the same gate runs before the dispatched operation. The challenge and token mechanism is identical across transports.

Tools and endpoints

The table documents each tool by registered tool name (Symbol column) and implementing class. Tools are grouped by tier and category. All Abstract Syntax Tree (AST) and mutation classes live under src/Tools/Ast and src/Tools/Ast/Mutation; the extraction class lives under src/Tools/Extraction; the remaining classes live under src/Tools/Core.

Core document tools

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`create_pdf`	`page_size` (default `A4`), `orientation` (`portrait`/`landscape`), `title`, `author`; none required.	Creates an in-memory document and one page; sets metadata when supplied.	JSON with `document_id`, `page_count`, `page_size`, `orientation`.	Returns an error result with the engine message on failure.	Class `CreatePdfTool`. Risk `RiskLevel::Caution`. Tier core. The returned `document_id` feeds every subsequent operation.
`add_page`	`document_id` (required), optional page size and orientation.	Appends a page to the document.	JSON with the new page count.	Error result when `document_id` is unknown.	Class `AddPageTool`. Risk `RiskLevel::Caution`. Tier core.
`add_text`	`document_id` (required), `text` (required), optional position and style.	Adds text to the document.	JSON document-state summary.	Error result when `document_id` is unknown.	Class `AddTextTool`. Risk `RiskLevel::Caution`. Tier core.
`add_image`	`document_id` (required), `source` (required: file path or base64), optional placement.	Adds an image from a path or base64 data.	JSON document-state summary.	Error result on unreadable source or unknown `document_id`.	Class `AddImageTool`. Risk `RiskLevel::Caution`. Tier core.
`add_table`	`document_id` (required), `html` (required).	Renders a Hypertext Markup Language (HTML) table into the document.	JSON document-state summary.	Error result on invalid markup or unknown `document_id`.	Class `AddTableTool`. Risk `RiskLevel::Caution`. Tier core.
`set_font`	`document_id` (required), `family` (required), optional size and style.	Sets the font for subsequent text operations.	JSON confirmation of the active font.	Error result on unknown font or `document_id`.	Class `SetFontTool`. Risk `RiskLevel::Caution`. Tier core.
`output_pdf`	`document_id` (required), `file_path` (optional), `destroy` (default `true`).	Finalizes the document; writes to `file_path`, or returns base64 when omitted; destroys the document by default.	JSON with `file_path` and `file_size`, or `base64` and `file_size`.	Error result when `document_id` is unknown; path containment failure when writing outside the base directory.	Class `OutputPdfTool`. Risk `RiskLevel::ApprovalRequired`. Tier core. Writing a file passes the confirmation gate; base64 mode does not.
`preview_layout`	`document_id` (required).	Returns a layout summary without rendering the final PDF.	JSON layout summary.	Error result when `document_id` is unknown.	Class `PreviewLayoutTool`. Risk `RiskLevel::Safe`. Tier core.
`parse_pdf`	`document_id` (required).	Inspects structural metadata: page count, fonts, images, encryption, and Info Dictionary.	JSON structural metadata.	Error result on a malformed document.	Class `ParsePdfTool`. Risk `RiskLevel::Safe`. Tier core. Registers only when `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` is `true` or `1`.

Core diagnostic tools

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`diagnostic.doctor`	none.	Runs a health check and returns structured environment diagnostics.	JSON environment report.	Error result on an internal check failure.	Class `DiagnosticDoctorTool`. Risk `RiskLevel::Safe`. Tier core. Requires no document and no confirmation.
`diagnostic.capabilities`	none.	Lists capabilities with tier and status information.	JSON capability list.	Error result on an internal failure.	Class `DiagnosticCapabilitiesTool`. Risk `RiskLevel::Safe`. Tier core.
`diagnostic.inspect`	`document_id` (required).	Inspects a PDF and returns structural metadata.	JSON structural metadata.	Error result when `document_id` is unknown.	Class `DiagnosticInspectTool`. Risk `RiskLevel::Safe`. Tier core.
`diagnostic.verify`	`document_id` (required), optional PDF/A or PDF/UA profile.	Verifies structural integrity; optionally validates PDF/A or PDF/UA by spawning a VeraPDF subprocess.	JSON verification report.	Error result on subprocess failure, timeout, or oversize input.	Class `DiagnosticVerifyTool`. Risk `RiskLevel::Caution`. Tier core. Input is capped at 50 mebibytes (MiB).

Core barcode tool

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`generate_barcode`	`payload` (required), `format` (for example QR Code, DataMatrix).	Generates a two-dimensional barcode module matrix for the payload.	JSON module matrix.	Error result on an unsupported `format` or invalid payload.	Class `BarcodeTool`. Risk `RiskLevel::Caution`. Tier core. `BarcodeTool` registers only when the core `barcode` encoder registry is present in the installed `nextpdf/core`; the registered tool name is `generate_barcode`.

Enterprise privacy tools

These tools wrap Enterprise privacy classes and register under the Enterprise tier only when those classes are autoloadable. They operate on plain-text content.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`redact_pdf`	`content` (required), optional detection options.	Destructively redacts personally identifiable information (PII) in plain-text content using the Enterprise redaction engine.	JSON with the redacted content and a SHA-256 hash.	Error result when the Enterprise classes are absent or detection fails.	Class `RedactPdfTool`. Risk `RiskLevel::Review`. Tier enterprise.
`deidentify_pdf`	`content` (required), `strategy` (redact or suppress).	Applies a systematic de-identification strategy to plain-text content using the Enterprise de-identifier.	JSON with the de-identified content.	Error result when the Enterprise classes are absent.	Class `DeIdentifyPdfTool`. Risk `RiskLevel::Review`. Tier enterprise.
`zone_redact_pdf`	`content` (required), `zones` (page plus normalized rectangle list).	Applies coordinate-based zone redactions using the Enterprise redaction engine.	JSON with the redacted content.	Error result on an invalid zone or absent Enterprise classes.	Class `ZoneRedactionTool`. Risk `RiskLevel::Review`. Tier enterprise.

Abstract syntax tree (AST) read tools

These tools ship with the server, register under the Pro tier, and are gated by NEXTPDF_AST_TOOLS_ENABLED (enabled by default). They are read-only.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`get_document_ast`	`pdf_data` (required).	Builds a semantic AST: a full node tree with citation anchors for every structural element.	JSON node tree plus an ETag for concurrency control.	Error result on a malformed document.	Class `GetDocumentAstTool`. Risk `RiskLevel::Safe`. Tier pro.
`get_ast_node`	`pdf_data` (required), `node_id` (required).	Retrieves a single AST node and all its children.	JSON node with children.	Error result on an unknown `node_id`.	Class `GetAstNodeTool`. Risk `RiskLevel::Safe`. Tier pro.
`get_ast_diff`	`original_pdf_data` (required), `modified_pdf_data` (required).	Structurally diffs two documents by comparing their semantic ASTs.	JSON added, removed, and changed nodes.	Error result on a malformed input document.	Class `GetAstDiffTool`. Risk `RiskLevel::Safe`. Tier pro.
`search_ast_nodes`	`pdf_data` (required), optional type, page index, and text filters.	Searches AST nodes by type, page index, or text content.	JSON flat list of matching nodes with shallow children.	Error result on a malformed document.	Class `SearchAstNodesTool`. Risk `RiskLevel::Safe`. Tier pro.
`extract_cited_text`	`pdf_data` (required), optional `headings_only`.	Extracts text blocks with citation anchors (page, bounding box, confidence).	JSON cited text blocks.	Error result on a malformed document.	Class `ExtractCitedTextTool`. Risk `RiskLevel::Safe`. Tier pro. Category `ast`.
`extract_cited_tables`	`pdf_data` (required).	Extracts table blocks with citation anchors; returns a row-major matrix of cells per Table node.	JSON table matrices with anchors.	Error result on a malformed document.	Class `ExtractCitedTablesTool`. Risk `RiskLevel::Safe`. Tier pro. Category `extraction`.

AST mutation tools

These tools ship with the server, register under the Pro tier, and are gated by NEXTPDF_MUTATION_TOOLS_ENABLED (enabled by default). All four are ApprovalRequired and use optimistic concurrency control (OCC) through an ETag.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`apply_ast_mutations`	`pdf_data`, `etag`, `idempotency_key`, `mutations` (all required).	Applies a batch of mutations atomically; replays the cached result for a repeated `idempotency_key`.	JSON with the mutated PDF and a new ETag.	OCC conflict when the ETag is stale; validation error on a malformed mutation.	Class `ApplyAstMutationsTool`. Risk `RiskLevel::ApprovalRequired`. Tier pro.
`delete_ast_node`	`pdf_data`, `node_id`, `etag` (all required).	Removes a node in overlay mode (original content is covered, not physically deleted).	JSON with the modified PDF and a new ETag.	OCC conflict when the ETag is stale; error on an unknown `node_id`.	Class `DeleteAstNodeTool`. Risk `RiskLevel::ApprovalRequired`. Tier pro.
`insert_ast_node`	`pdf_data`, `parent_node_id`, `position`, `etag`, `node` (all required).	Inserts a new node as a child of the parent at the specified position.	JSON with the modified PDF and a new ETag.	OCC conflict when the ETag is stale; validation error on a malformed node.	Class `InsertAstNodeTool`. Risk `RiskLevel::ApprovalRequired`. Tier pro.
`update_ast_node`	`pdf_data`, `node_id`, `etag`, `updates` (all required).	Updates the text content of a node.	JSON with the modified PDF and a new ETag.	OCC conflict when the ETag is stale; error on an unknown `node_id`.	Class `UpdateAstNodeTool`. Risk `RiskLevel::ApprovalRequired`. Tier pro.

Request and response schema

The gRPC transport defines the server’s typed schema in the Protocol Buffers package nextpdf.connect.v1, in proto/nextpdf/connect/v1/*.proto. The service and its messages are the canonical schema symbols.

Service `NextPDFConnect`

The service NextPDFConnect exposes unary and server-streaming RPCs. The schema symbols are the RPC method names and the request and response messages they carry.

RPC	Request message	Response message	Shape
`Render`	`RenderRequest`	`RenderResponse`	Unary. Synchronous stateless render.
`RenderStream`	`RenderRequest`	`RenderChunk` (stream)	Server-streaming. Render delivered as ordered chunks.
`SubmitJob`	`SubmitJobRequest`	`JobResponse`	Unary. Submit an asynchronous render job.
`GetJobStatus`	`GetJobStatusRequest`	`JobResponse`	Unary. Poll job status.
`GetJobResult`	`GetJobResultRequest`	`RenderResponse`	Unary. Download a completed result.
`GetJobResultStream`	`GetJobResultRequest`	`RenderChunk` (stream)	Server-streaming. Download a completed result as chunks.
`CancelJob`	`CancelJobRequest`	`JobResponse`	Unary. Cancel or delete a job.
`CreateSession`	`CreateSessionRequest`	`SessionResponse`	Unary. Create a document-building session.
`GetSession`	`GetSessionRequest`	`SessionResponse`	Unary. Get session metadata.
`DestroySession`	`DestroySessionRequest`	`DestroySessionResponse`	Unary. Destroy a session and its document.
`SessionOperation`	`SessionOperationRequest`	`SessionResponse`	Unary. Execute an operation on a session document.
`SessionRender`	`SessionRenderRequest`	`RenderResponse`	Unary. Render a session document to PDF.
`SessionRenderStream`	`SessionRenderRequest`	`RenderChunk` (stream)	Server-streaming. Render a session document as chunks.
`ExecuteCapability`	`CapabilityRequest`	`CapabilityResponse`	Unary. Execute a tier-gated capability operation.
`GetCapabilities`	`GetCapabilitiesRequest`	`GetCapabilitiesResponse`	Unary. List the capabilities for the authenticated client.
`HealthCheck`	`HealthCheckRequest`	`HealthCheckResponse`	Unary. Liveness probe.
`ReadinessCheck`	`ReadinessCheckRequest`	`ReadinessCheckResponse`	Unary. Readiness probe.

Message symbols

The request and response messages are the schema’s structural symbols. The render messages, RenderRequest, RenderResponse, and the streaming RenderChunk, carry the page size, orientation, ordered operations, and resulting PDF bytes. The job messages, SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest, and JobResponse, model the asynchronous job lifecycle, with job metadata held in the JobData message. The session messages, CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest, and SessionRenderRequest, model the stateful session lifecycle, with session metadata held in the SessionData message. The capability messages, CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest, and GetCapabilitiesResponse, carry tier-gated operation dispatch and introspection. The system messages, HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest, and ReadinessCheckResponse, carry liveness and readiness status.

The shipped .proto files are the wire contract of record; see the gRPC transport reference on gRPC transport.

Error model

The server reports failures with each transport’s native error mechanism. Each transport preserves the same logical condition; only the encoding differs.

MCP

MCP errors are JSON-RPC 2.0 error objects. An unknown method returns method-not-found (-32601); a message that is not valid JSON-RPC returns invalid-request (-32600); unparseable input returns parse-error (-32700). A failing tool returns a successful JSON-RPC response whose content marks the error, rather than a transport-level error, so the agent can read the message. A confirmation challenge for an ApprovalRequired tool is also a successful response, not an error.

REST

REST uses Hypertext Transfer Protocol (HTTP) status codes with the semantics defined by RFC 9110. A 200 carries the result; a 400 is returned when a request field fails format validation; a 401 is returned when no valid API key is presented and carries a WWW-Authenticate: Bearer challenge header; a 403 is returned when a valid key’s tier is not entitled to the operation; a 404 is returned when a tier-gated route is not registered because its package is absent. Machine-readable error bodies are Problem Details documents per RFC 9457, served with the application/problem+json media type and a stable type Uniform Resource Identifier (URI) for each condition. Field-level validation failures are listed in the body. As a path-traversal hardening measure, a document_id that does not match the pattern doc_[a-f0-9]{24} is rejected with 400 before the tool runs. REST transport documents the REST middleware pipeline and route table.

gRPC

gRPC uses standard gRPC status codes. A missing, malformed, unknown, disabled, or expired token fails the call with UNAUTHENTICATED rather than an HTTP status. Rich error detail mirrors the REST Problem Details shape and is carried in the gRPC status details, so the error type URI is consistent across transports.

See also RFC 9110 (HTTP Semantics) for status-code semantics and RFC 9457 (Problem Details for HTTP APIs) for the error-body format.

RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
RFC 9457: https://www.rfc-editor.org/rfc/rfc9457

Rate limits and quotas

The REST transport applies per-Internet-Protocol-address (per-IP) and per-client rate limiting in its middleware pipeline, plus body-size and tier-payload limits and a per-request timeout. These ceilings are configuration values, not hard-coded constants:

Per-tier payload ceilings (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) and the matching timeouts apply on REST according to the authenticated key’s tier. See Configuration.
The in-memory document store is bounded by max_documents (default 50) and document_ttl (default 1800 seconds).
Rate-limit and idempotency state is per-worker unless NEXTPDF_REDIS_HOST is configured for a shared store. See Deployment.

When rate-limit and idempotency stores are shared, repeated identical asynchronous job submissions are de-duplicated by the idempotency_key. The MCP transport handles one request at a time over pipes and de-duplicates a repeated request id from a 64-entry buffer instead of applying network rate limits.

Development notes

Read tool names, classes, and risk tiers from the source under src/Tools/; do not assume a fixed total. Query the running server for the authoritative count, as shown on Tool catalog.
Regenerate gRPC client stubs from the shipped proto/nextpdf/connect/v1/*.proto files; the package and namespace are nextpdf.connect.v1. Do not hand-edit generated message classes.
An ApprovalRequired tool answers with a confirmation challenge on first call. Build the retry path — relay the challenge, then re-invoke with _confirmation_token — before you ship an integration that drives output_pdf or any mutation tool.
A tier-gated route or capability that is not installed is not an authentication failure: REST returns 404 for an absent route, and gRPC ExecuteCapability reports the operation as unavailable. Treat an absent Pro or Enterprise tier as expected operation, not a fault.
Keep API keys out of source control; mount them from a secret file and prefer the hot-reloading file key store so rotation needs no restart. See Security and operations.