Referenz zur Connect-REST-API

Auf einen Blick

NextPDF Connect stellt seine Werkzeug-Registry per HTTP als REST-Transport bereit und beschreibt sie über einen OpenAPI 3.1-Vertrag. Diese Seite dient als Referenz für diese Schnittstelle: Basis-URL, Authentifizierung, Operationsgruppen und Fehlermodell. Die vollständige maschinenlesbare Spezifikation ist veröffentlicht, sodass Sie sie in einen interaktiven Explorer, einen Client-Generator oder einen Request-Client laden können, ohne etwas von Hand kopieren zu müssen.

Den transportunabhängigen Werkzeugkatalog (dieselben Operationen über das Model Context Protocol und gRPC sowie REST) finden Sie in der Connect-API-Referenz. Informationen zur RoadRunner-Pipeline, zum Deployment und zur Einrichtung der Authentifizierung finden Sie im REST-Transport-Leitfaden.

Basis-URL und Authentifizierung

Der REST-Transport lauscht auf dem Host und Port, die für Ihr Deployment konfiguriert sind. In einer lokalen Ausführung ist das http://localhost:8080; in der Produktion ist es die Adresse vor Ihrem Worker-Pool.

Die Authentifizierung erfolgt über ein Bearer-Token. Senden Sie den API-Schlüssel bei jeder Anfrage an eine stufengesteuerte Route im Authorization-Header:

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"}]}'

Schreibgeschützte Liveness- und Readiness-Probes benötigen kein Token.

Operationen

Die Verfügbarkeit ist stufengesteuert. Der Open-Source-Core stellt die Dokument-, Render-, Session- und Job-Operationen bereit. Signieren, Formularausfüllen, Schwärzen, Vergleichen, Barrierefreiheitsprüfung und Optimierung erfordern eine kommerzielle Edition, die zusätzlich zum Server installiert ist. Den maßgeblichen Funktionsumfang eines bestimmten Deployments gibt der Capabilities-Endpunkt zurück. Fragen Sie ihn ab, statt von einer festen Liste auszugehen.

Health und Lebenszyklus

Methode	Pfad	Zweck
GET	/healthz	Liveness-Probe. Keine Authentifizierung.
GET	/readyz	Readiness-Probe (Abhängigkeiten und Worker-Pool bereit). Keine Authentifizierung.
GET	/api/v1/capabilities	Die Werkzeuge und Stufen, die dieses Deployment tatsächlich bereitstellt. Fragen Sie diesen Endpunkt zuerst ab.

Rendern und Dokumente

Methode	Pfad	Zweck
POST	/api/v1/render	Rendert ein Dokument aus einer geordneten Liste von Operationen und gibt das PDF zurück.
POST	/api/v1/extract-text	Extrahiert Textinhalt aus einem PDF.
POST	/api/v1/merge	Führt mehrere PDF-Eingaben zu einem einzigen Dokument zusammen.
POST	/api/v1/split	Teilt ein PDF in mehrere Dokumente auf.

Asynchrone Jobs

Methode	Pfad	Zweck
POST	/api/v1/jobs	Reicht eine lang laufende Operation als Job ein.
GET	/api/v1/jobs/{id}	Fragt den Jobstatus ab.
GET	/api/v1/jobs/{id}/result	Ruft das Ergebnis des abgeschlossenen Jobs ab.

Sessions

Sessions halten ein Dokument über mehrere Aufrufe hinweg offen, sodass Sie es schrittweise aufbauen und am Ende einmal rendern können.

Methode	Pfad	Zweck
POST	/api/v1/sessions	Öffnet eine Session.
GET / DELETE	/api/v1/sessions/{sessionId}	Inspiziert oder schließt eine Session.
POST	/api/v1/sessions/{sessionId}/pages	Fügt eine Seite hinzu.
POST	/api/v1/sessions/{sessionId}/text	Fügt Text hinzu.
POST	/api/v1/sessions/{sessionId}/images	Fügt ein Bild hinzu.
POST	/api/v1/sessions/{sessionId}/tables	Fügt eine Tabelle hinzu.
POST	/api/v1/sessions/{sessionId}/html	Fügt gerendertes HTML hinzu.
POST	/api/v1/sessions/{sessionId}/font	Setzt die aktive Schriftart.
POST	/api/v1/sessions/{sessionId}/render	Rendert das Session-Dokument.

Operationen der kommerziellen Editionen

Diese Routen werden nur registriert, wenn die passende kommerzielle Edition installiert ist. Für mehrere davon ist im Human-in-the-Loop-Bestätigungsablauf eine Genehmigung erforderlich; siehe Risikostufen.

Methode	Pfad	Zweck
POST	/api/v1/sign	Wendet eine digitale Signatur an.
POST	/api/v1/fill-form	Füllt ein interaktives Formular aus.
POST	/api/v1/redact	Schwärzt Inhalte.
POST	/api/v1/compare	Vergleicht zwei PDF-Dokumente.
POST	/api/v1/check-accessibility	Führt eine strukturelle Barrierefreiheitsprüfung durch.
POST	/api/v1/optimize	Optimiert und verkleinert ein Dokument.

Fehlermodell

Der REST-Transport verwendet HTTP-Statuscodes gemäß der in RFC 9110 definierten Semantik: 2xx für Erfolg, 4xx für eine Anfrage, die der Aufrufer beheben muss (400 fehlerhafter Body, 401 fehlendes oder ungültiges Token, 403 Stufe oder Genehmigung verweigert, 404 unbekannte Route oder unbekannter Job, 409 Idempotenzkonflikt, 422 eine wohlgeformte Anfrage, die die Engine nicht verarbeiten kann) und 5xx für einen serverseitigen Fehler. Eine 401-Antwort enthält eine WWW-Authenticate-Challenge.

Fehler-Bodys sind application/problem+json-Dokumente gemäß RFC 9457 (Problem Details for HTTP APIs): mit stabilem type, kurzem title, numerischem status und menschenlesbarem detail. Gleichen Sie anhand von type ab, nicht anhand der detail-Zeichenkette. Die normativen Definitionen finden Sie in RFC 9110 (HTTP Semantics) und RFC 9457.

Reichen Sie zustandsändernde Anfragen mit einem Idempotency-Key-Header ein, damit eine wiederholte Anfrage nur einmal verarbeitet wird.

Maschinenlesbare Spezifikation

Der vollständige Vertrag ist als statisches OpenAPI 3.1-Dokument veröffentlicht:

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

Nutzen Sie es als alleinige maßgebliche Quelle für die REST-Oberfläche:

1. Öffnen Sie den interaktiven API-Explorer — eine im Browser laufende, selbst gehostete Scalar-Referenz, die aus diesem Vertrag generiert wird —, um jede Operation mit ihren Request- und Response-Schemas zu lesen und auszuprobieren.
2. Importieren Sie es in einen Request-Client wie Postman oder Insomnia.
3. Generieren Sie mit einem OpenAPI-Generator einen typisierten Client für Ihre Sprache.

Das Dokument ist ein statischer, an die Paketversion gebundener Vertrag. Es wird nicht von einem Live-Endpunkt ausgeliefert und bleibt daher über Deployments hinweg stabil.

Siehe auch

• Connect-API-Referenz — der vollständige Werkzeugkatalog für MCP, REST und gRPC.
• REST-Transport-Leitfaden — RoadRunner-Pipeline, Bearer-Authentifizierung und Stufen-Routing.
• NextPDF Connect-Überblick — was der Server ist und wie Sie ihn betreiben.