NextPDF Connect API-Referenz

Auf einen Blick

Diese Seite ist die Symbolreferenz für den NextPDF Connect-Server (nextpdf/server). Sie führt jedes Tool mit seinem registrierten Tool-Namen und seiner implementierenden Klasse auf und dokumentiert den gRPC-Dienst NextPDFConnect mit seinen Remote-Procedure-Call-Methoden (RPC) sowie den Anfrage- und Antwortnachrichten. Außerdem beschreibt sie den gemeinsamen Vertrag für Authentifizierung, Fehler und Ratenlimits, den alle Transporte nutzen.

Der Server stellt eine einzige Tool-Registry über drei Transporte bereit — das Model Context Protocol (MCP) über Standardeingabe und -ausgabe, eine Representational-State-Transfer-(REST-)Programmierschnittstelle (API) und gRPC. Die Wire-Details jedes Transports stehen auf einer eigenen Seite: siehe MCP-Transport, REST-Transport und gRPC-Transport. Diese Seite ist der Katalog der Symbole, die diese Transporte bereitstellen.

Die unten aufgeführten Tool-Namen, Klassen und Risikostufen werden aus den Tool-Implementierungen in src/Tools/ abgeleitet. Wie viele Tools ein Deployment tatsächlich bereitstellt, ist eine Laufzeiteigenschaft; siehe Tool-Katalog. Wie die Stufe aufgelöst wird, erklärt Boot und Discovery.

Transport-Verfügbarkeit

Ein Tool ist über den Transport erreichbar, den das jeweilige Deployment ausführt. Die Transporte sind eigenständige Prozesse; wird einer davon gestartet, starten die anderen dadurch nicht.

Transport	Einstiegspunkt	Wire-Format	Authentifizierung
MCP	bin/nextpdf-mcp	JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 über stdio	Prozessgrenze des Betriebssystems (kein API-Schlüssel)
REST	bin/nextpdf-server	HTTP, OpenAPI 3.1	Bearer-API-Schlüssel im Authorization-Header
gRPC	bin/nextpdf-grpc	Protocol Buffers, Paket nextpdf.connect.v1	Bearer-Token in den authorization-Aufrufmetadaten

Über MCP wird ein Tool per tools/call mit dem registrierten Tool-Namen aufgerufen. Über REST und gRPC erreichen Sie dieselben Engine-Fähigkeiten über die Render-, Operations- und Capability-Oberflächen; siehe die Routentabelle des REST-Transports und die RPC-Tabelle des gRPC-Transports.

Authentifizierung und Risikostufe

Authentifizierung per API-Schlüssel

Die REST- und gRPC-Transporte verlangen bei jeder Anfrage einen Bearer-API-Schlüssel, ausgenommen die nicht authentifizierten Health-Probes. Ein Schlüssel hat die Form npk_live_{kid}_{secret}: Die kid ist eine achtstellige Kennung für die Datensatzsuche, und das Secret enthält die Entropie. Der Server speichert nur einen SHA-256-Digest des Schlüssels und vergleicht das vorgelegte Token in konstanter Zeit, sodass ein falscher Schlüssel über das Timing nichts preisgibt. REST liest das Token aus dem Authorization: Bearer …-Header; gRPC liest dasselbe Token aus den authorization-Aufrufmetadaten. Der MCP-stdio-Transport hat keinen API-Schlüssel, weil er ein lokaler Subprozess ist, dem sein aufrufender Client vertraut. Das Authentifizierungsmodell ist vollständig unter Sicherheit und Betrieb dokumentiert.

Die vier Risikostufen

Jedes Tool deklariert eine von vier geordneten Risikostufen, definiert durch das Enum RiskLevel in src/Config/RiskLevel.php.

Stufe	Enum-Case	Wert	Wirkung
Safe	RiskLevel::Safe	0	Nur lesend, keine Seiteneffekte. Wird automatisch ausgeführt.
Caution	RiskLevel::Caution	1	Erzeugt oder verändert In-Memory-Zustand. Wird automatisch ausgeführt und im Audit protokolliert.
Review	RiskLevel::Review	2	Erzeugt Ausgaben, die missbraucht werden könnten. Wird automatisch ausgeführt und im Audit protokolliert.
ApprovalRequired	RiskLevel::ApprovalRequired	3	Destruktiv, rechtlich oder datenschutzkritisch. Erfordert eine Bestätigung durch einen Menschen.

Das effektive Risiko eines Tools stammt aus genau zwei Quellen: der eigenen riskLevel()-Deklaration des Tools und einem optionalen Konfigurations-Override des Betreibers, der das Risiko nur erhöhen, ein ApprovalRequired-Tool aber nie herabstufen darf. Siehe dazu HITL-Risikostufen und Konfiguration.

Wie Bestätigungs-Token fließen

Wenn ein ApprovalRequired-Tool ohne gültiges Token aufgerufen wird, gibt das ConfirmationGate (src/Mcp/ConfirmationGate.php) ein nur einmal verwendbares Challenge-Token zurück, statt das Tool auszuführen. Der Agent leitet die Challenge an einen Menschen weiter und ruft dann dasselbe Tool erneut auf, wobei er das ausgestellte Token im Argument _confirmation_token mitgibt. Das Token bindet den Tool-Namen, eine zufällige Nonce und eine Lebensdauer von 300 Sekunden (Time-to-live, TTL). Es bindet nicht die Argumente und ist kein Authentifizierungs-Credential. Bei REST authentifiziert der Bearer-API-Schlüssel weiterhin die Anfrage, und dasselbe Gate läuft im gemeinsamen Tool-Executor vor der durch das Gate geschützten Operation. Bei gRPC läuft dasselbe Gate vor dem Dispatch der Operation. Der Challenge- und Token-Mechanismus ist über alle Transporte hinweg identisch.

Tools und Endpunkte

Die Tabelle dokumentiert jedes Tool mit seinem registrierten Tool-Namen (Spalte Symbol) und benennt die implementierende Klasse. Die Tools sind nach Stufe und Kategorie gruppiert. Alle AST- und Mutationsklassen liegen unter src/Tools/Ast und src/Tools/Ast/Mutation; die Extraction-Klasse liegt unter src/Tools/Extraction; die übrigen Klassen liegen unter src/Tools/Core.

Kern-Dokumenttools

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
create_pdf	page_size (Standard A4), orientation (portrait/landscape), title, author; keine erforderlich.	Erzeugt ein In-Memory-Dokument und eine Seite; setzt Metadaten, sofern angegeben.	JSON mit document_id, page_count, page_size, orientation.	Gibt bei einem Fehlschlag ein Fehlerergebnis mit der Engine-Meldung zurück.	Klasse CreatePdfTool. Risiko RiskLevel::Caution. Stufe core. Die zurückgegebene document_id speist jede nachfolgende Operation.
add_page	document_id (erforderlich), optionale Seitengröße und Ausrichtung.	Hängt dem Dokument eine Seite an.	JSON mit der neuen Seitenanzahl.	Fehlerergebnis, wenn die document_id unbekannt ist.	Klasse AddPageTool. Risiko RiskLevel::Caution. Stufe core.
add_text	document_id (erforderlich), text (erforderlich), optionale Position und optionaler Stil.	Fügt dem Dokument Text hinzu.	JSON-Zusammenfassung des Dokumentzustands.	Fehlerergebnis, wenn die document_id unbekannt ist.	Klasse AddTextTool. Risiko RiskLevel::Caution. Stufe core.
add_image	document_id (erforderlich), source (erforderlich: Dateipfad oder base64), optionale Platzierung.	Fügt ein Bild aus einem Pfad oder aus base64-Daten hinzu.	JSON-Zusammenfassung des Dokumentzustands.	Fehlerergebnis bei nicht lesbarer Quelle oder unbekannter document_id.	Klasse AddImageTool. Risiko RiskLevel::Caution. Stufe core.
add_table	document_id (erforderlich), html (erforderlich).	Rendert eine Hypertext-Markup-Language-Tabelle (HTML) in das Dokument.	JSON-Zusammenfassung des Dokumentzustands.	Fehlerergebnis bei ungültigem Markup oder unbekannter document_id.	Klasse AddTableTool. Risiko RiskLevel::Caution. Stufe core.
set_font	document_id (erforderlich), family (erforderlich), optionale Größe und optionaler Stil.	Setzt die Schriftart für nachfolgende Textoperationen.	JSON-Bestätigung der aktiven Schriftart.	Fehlerergebnis bei unbekannter Schriftart oder document_id.	Klasse SetFontTool. Risiko RiskLevel::Caution. Stufe core.
output_pdf	document_id (erforderlich), file_path (optional), destroy (Standard true).	Finalisiert das Dokument; schreibt nach file_path oder gibt base64 zurück, wenn weggelassen; zerstört das Dokument standardmäßig.	JSON mit file_path und file_size oder mit base64 und file_size.	Fehlerergebnis, wenn die document_id unbekannt ist; Fehler bei der Pfadeingrenzung, wenn außerhalb des Basisverzeichnisses geschrieben wird.	Klasse OutputPdfTool. Risiko RiskLevel::ApprovalRequired. Stufe core. Das Schreiben einer Datei durchläuft das Bestätigungs-Gate; der base64-Modus nicht.
preview_layout	document_id (erforderlich).	Gibt eine Layout-Zusammenfassung zurück, ohne das endgültige PDF zu rendern.	JSON-Layout-Zusammenfassung.	Fehlerergebnis, wenn die document_id unbekannt ist.	Klasse PreviewLayoutTool. Risiko RiskLevel::Safe. Stufe core.
parse_pdf	document_id (erforderlich).	Inspiziert strukturelle Metadaten: Seitenanzahl, Schriftarten, Bilder, Verschlüsselung und Info-Dictionary.	JSON mit strukturellen Metadaten.	Fehlerergebnis bei einem fehlerhaften Dokument.	Klasse ParsePdfTool. Risiko RiskLevel::Safe. Stufe core. Wird nur registriert, wenn NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED true oder 1 ist.

Kern-Diagnosetools

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
diagnostic.doctor	keine.	Führt einen Health-Check aus und gibt strukturierte Umgebungsdiagnosen zurück.	JSON-Umgebungsbericht.	Fehlerergebnis bei einem internen Prüffehler.	Klasse DiagnosticDoctorTool. Risiko RiskLevel::Safe. Stufe core. Benötigt kein Dokument und keine Bestätigung.
diagnostic.capabilities	keine.	Listet Fähigkeiten mit Stufen- und Statusinformationen auf.	JSON-Capability-Liste.	Fehlerergebnis bei einem internen Fehler.	Klasse DiagnosticCapabilitiesTool. Risiko RiskLevel::Safe. Stufe core.
diagnostic.inspect	document_id (erforderlich).	Inspiziert ein PDF und gibt strukturelle Metadaten zurück.	JSON mit strukturellen Metadaten.	Fehlerergebnis, wenn die document_id unbekannt ist.	Klasse DiagnosticInspectTool. Risiko RiskLevel::Safe. Stufe core.
diagnostic.verify	document_id (erforderlich), optionales PDF/A- oder PDF/UA-Profil.	Verifiziert die strukturelle Integrität; validiert optional PDF/A oder PDF/UA, indem ein VeraPDF-Subprozess gestartet wird.	JSON-Verifizierungsbericht.	Fehlerergebnis bei Subprozessfehler, Timeout oder zu großer Eingabe.	Klasse DiagnosticVerifyTool. Risiko RiskLevel::Caution. Stufe core. Die Eingabe ist auf 50 Mebibyte (MiB) begrenzt.

Kern-Barcodetool

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
generate_barcode	payload (erforderlich), format (zum Beispiel QR Code, DataMatrix).	Erzeugt eine zweidimensionale Barcode-Modulmatrix für den Payload.	JSON-Modulmatrix.	Fehlerergebnis bei einem nicht unterstützten format oder ungültigem Payload.	Klasse BarcodeTool. Risiko RiskLevel::Caution. Stufe core. Das BarcodeTool registriert sich nur, wenn die Encoder-Registry für barcode im installierten nextpdf/core vorhanden ist; der registrierte Tool-Name lautet generate_barcode.

Enterprise-Datenschutz-Tools

Diese Tools kapseln Enterprise-Datenschutzklassen und registrieren sich nur dann unter der Enterprise-Stufe, wenn diese Klassen per Autoload verfügbar sind. Sie arbeiten mit Klartextinhalten.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
redact_pdf	content (erforderlich), optionale Erkennungsoptionen.	Redigiert personenbezogene Daten (PII) in Klartextinhalten destruktiv mithilfe der Enterprise-Redaktions-Engine.	JSON mit dem redigierten Inhalt und einem SHA-256-Hash.	Fehlerergebnis, wenn die Enterprise-Klassen fehlen oder die Erkennung fehlschlägt.	Klasse RedactPdfTool. Risiko RiskLevel::Review. Stufe enterprise.
deidentify_pdf	content (erforderlich), strategy (redact oder suppress).	Wendet mithilfe des Enterprise-De-Identifiers eine systematische De-Identifizierungsstrategie auf Klartextinhalte an.	JSON mit dem de-identifizierten Inhalt.	Fehlerergebnis, wenn die Enterprise-Klassen fehlen.	Klasse DeIdentifyPdfTool. Risiko RiskLevel::Review. Stufe enterprise.
zone_redact_pdf	content (erforderlich), zones (Seite plus normalisierte Rechteckliste).	Wendet mithilfe der Enterprise-Redaktions-Engine koordinatenbasierte Zonenredaktionen an.	JSON mit dem redigierten Inhalt.	Fehlerergebnis bei einer ungültigen Zone oder fehlenden Enterprise-Klassen.	Klasse ZoneRedactionTool. Risiko RiskLevel::Review. Stufe enterprise.

Abstract-Syntax-Tree-(AST-)Lesetools

Diese Tools werden mit dem Server ausgeliefert, registrieren sich unter der Pro-Stufe und werden durch NEXTPDF_AST_TOOLS_ENABLED gesteuert (standardmäßig aktiviert). Sie lesen nur.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
get_document_ast	pdf_data (erforderlich).	Baut einen semantischen AST auf: einen vollständigen Knotenbaum mit Zitatankern für jedes strukturelle Element.	JSON-Knotenbaum mit einem ETag für die Nebenläufigkeitssteuerung.	Fehlerergebnis bei einem fehlerhaften Dokument.	Klasse GetDocumentAstTool. Risiko RiskLevel::Safe. Stufe pro.
get_ast_node	pdf_data (erforderlich), node_id (erforderlich).	Ruft einen einzelnen AST-Knoten und alle seine Kinder ab.	JSON-Knoten mit Kindern.	Fehlerergebnis bei einer unbekannten node_id.	Klasse GetAstNodeTool. Risiko RiskLevel::Safe. Stufe pro.
get_ast_diff	original_pdf_data (erforderlich), modified_pdf_data (erforderlich).	Erstellt strukturelle Diffs zweier Dokumente durch Vergleich ihrer semantischen ASTs.	JSON mit hinzugefügten, entfernten und geänderten Knoten.	Fehlerergebnis bei einem fehlerhaften Eingabedokument.	Klasse GetAstDiffTool. Risiko RiskLevel::Safe. Stufe pro.
search_ast_nodes	pdf_data (erforderlich), optionale Filter für Typ, Seitenindex und Text.	Durchsucht AST-Knoten nach Typ, Seitenindex oder Textinhalt.	Flache JSON-Liste passender Knoten mit flachen Kindern.	Fehlerergebnis bei einem fehlerhaften Dokument.	Klasse SearchAstNodesTool. Risiko RiskLevel::Safe. Stufe pro.
extract_cited_text	pdf_data (erforderlich), optional headings_only.	Extrahiert Textblöcke mit Zitatankern (Seite, Bounding-Box, Konfidenz).	JSON mit zitierten Textblöcken.	Fehlerergebnis bei einem fehlerhaften Dokument.	Klasse ExtractCitedTextTool. Risiko RiskLevel::Safe. Stufe pro. Kategorie ast.
extract_cited_tables	pdf_data (erforderlich).	Extrahiert Tabellenblöcke mit Zitatankern; gibt eine zeilenweise Matrix von Zellen pro Table-Knoten zurück.	JSON-Tabellenmatrizen mit Ankern.	Fehlerergebnis bei einem fehlerhaften Dokument.	Klasse ExtractCitedTablesTool. Risiko RiskLevel::Safe. Stufe pro. Kategorie extraction.

AST-Mutationstools

Diese Tools werden mit dem Server ausgeliefert, registrieren sich unter der Pro-Stufe und werden durch NEXTPDF_MUTATION_TOOLS_ENABLED gesteuert (standardmäßig aktiviert). Alle vier sind ApprovalRequired und nutzen optimistische Nebenläufigkeitssteuerung (OCC) über ein ETag.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
apply_ast_mutations	pdf_data, etag, idempotency_key, mutations (alle erforderlich).	Wendet einen Stapel von Mutationen atomar an; spielt das zwischengespeicherte Ergebnis für einen wiederholten idempotency_key erneut ab.	JSON mit dem mutierten PDF und einem neuen ETag.	OCC-Konflikt, wenn das ETag veraltet ist; Validierungsfehler bei einer fehlerhaften Mutation.	Klasse ApplyAstMutationsTool. Risiko RiskLevel::ApprovalRequired. Stufe pro.
delete_ast_node	pdf_data, node_id, etag (alle erforderlich).	Entfernt einen Knoten im Overlay-Modus (der ursprüngliche Inhalt wird überdeckt, nicht physisch gelöscht).	JSON mit dem geänderten PDF und einem neuen ETag.	OCC-Konflikt, wenn das ETag veraltet ist; Fehler bei einer unbekannten node_id.	Klasse DeleteAstNodeTool. Risiko RiskLevel::ApprovalRequired. Stufe pro.
insert_ast_node	pdf_data, parent_node_id, position, etag, node (alle erforderlich).	Fügt einen neuen Knoten als Kind des Elternknotens an der Position ein.	JSON mit dem geänderten PDF und einem neuen ETag.	OCC-Konflikt, wenn das ETag veraltet ist; Validierungsfehler bei einem fehlerhaften Knoten.	Klasse InsertAstNodeTool. Risiko RiskLevel::ApprovalRequired. Stufe pro.
update_ast_node	pdf_data, node_id, etag, updates (alle erforderlich).	Aktualisiert den Textinhalt eines Knotens.	JSON mit dem geänderten PDF und einem neuen ETag.	OCC-Konflikt, wenn das ETag veraltet ist; Fehler bei einer unbekannten node_id.	Klasse UpdateAstNodeTool. Risiko RiskLevel::ApprovalRequired. Stufe pro.

Anfrage- und Antwortschema

Der gRPC-Transport definiert das typisierte Schema für den Server im Protocol-Buffers-Paket nextpdf.connect.v1, in proto/nextpdf/connect/v1/*.proto. Der Dienst und seine Nachrichten sind die kanonischen Schemasymbole.

Dienst NextPDFConnect

Der Dienst NextPDFConnect stellt unäre und Server-Streaming-RPCs bereit. Die Schemasymbole sind die RPC-Methodennamen sowie die Anfrage- und Antwortnachrichten, die sie transportieren.

RPC	Anfragenachricht	Antwortnachricht	Form
Render	RenderRequest	RenderResponse	Unär. Synchrones, zustandsloses Rendern.
RenderStream	RenderRequest	RenderChunk (Stream)	Server-Streaming. Render-Ausgabe wird als geordnete Chunks geliefert.
SubmitJob	SubmitJobRequest	JobResponse	Unär. Reicht einen asynchronen Render-Job ein.
GetJobStatus	GetJobStatusRequest	JobResponse	Unär. Fragt den Job-Status ab.
GetJobResult	GetJobResultRequest	RenderResponse	Unär. Lädt ein abgeschlossenes Ergebnis herunter.
GetJobResultStream	GetJobResultRequest	RenderChunk (Stream)	Server-Streaming. Lädt ein abgeschlossenes Ergebnis als Chunks herunter.
CancelJob	CancelJobRequest	JobResponse	Unär. Bricht einen Job ab oder löscht ihn.
CreateSession	CreateSessionRequest	SessionResponse	Unär. Erstellt eine Sitzung zum Dokumentaufbau.
GetSession	GetSessionRequest	SessionResponse	Unär. Ruft Sitzungsmetadaten ab.
DestroySession	DestroySessionRequest	DestroySessionResponse	Unär. Zerstört eine Sitzung und ihr Dokument.
SessionOperation	SessionOperationRequest	SessionResponse	Unär. Führt eine Operation auf einem Sitzungsdokument aus.
SessionRender	SessionRenderRequest	RenderResponse	Unär. Rendert ein Sitzungsdokument als PDF.
SessionRenderStream	SessionRenderRequest	RenderChunk (Stream)	Server-Streaming. Rendert ein Sitzungsdokument als Chunks.
ExecuteCapability	CapabilityRequest	CapabilityResponse	Unär. Führt eine stufengesteuerte Capability-Operation aus.
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	Unär. Listet die Fähigkeiten für den authentifizierten Client auf.
HealthCheck	HealthCheckRequest	HealthCheckResponse	Unär. Liveness-Probe.
ReadinessCheck	ReadinessCheckRequest	ReadinessCheckResponse	Unär. Readiness-Probe.

Nachrichtensymbole

Die Anfrage- und Antwortnachrichten sind die strukturellen Symbole des Schemas. Die Render-Nachrichten — RenderRequest, RenderResponse und das streamende RenderChunk — transportieren die Seitengröße, die Ausrichtung, die geordneten Operationen und die resultierenden PDF-Bytes. Die Job-Nachrichten — SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest und JobResponse — modellieren den asynchronen Job-Lebenszyklus; die Job-Metadaten liegen in der Nachricht JobData. Die Sitzungsnachrichten — CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest und SessionRenderRequest — modellieren den zustandsbehafteten Sitzungslebenszyklus; die Sitzungsmetadaten liegen in der Nachricht SessionData. Die Capability-Nachrichten — CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest und GetCapabilitiesResponse — transportieren den stufengesteuerten Operations-Dispatch und die Introspektion. Die System-Nachrichten — HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest und ReadinessCheckResponse — transportieren den Liveness- und Readiness-Status.

Die ausgelieferten .proto-Dateien sind der maßgebliche Vertrag auf Wire-Ebene; die gRPC-Transport-Referenz steht auf gRPC-Transport.

Fehlermodell

Der Server meldet Fehlschläge über den nativen Fehlermechanismus des jeweiligen Transports. Jeder Transport bildet dieselbe logische Bedingung ab; nur die Kodierung unterscheidet sich.

MCP

MCP-Fehler sind JSON-RPC-2.0-Fehlerobjekte. Eine unbekannte Methode gibt method-not-found zurück (-32601); eine Nachricht, die kein gültiges JSON-RPC ist, gibt invalid-request zurück (-32600); nicht parsbare Eingabe gibt parse-error zurück (-32700). Ein Tool, das fehlschlägt, gibt statt eines Fehlers auf Transportebene eine erfolgreiche JSON-RPC-Antwort zurück, deren Inhalt den Fehler markiert, sodass der Agent die Meldung lesen kann. Eine Bestätigungs-Challenge für ein ApprovalRequired-Tool ist ebenfalls eine erfolgreiche Antwort, kein Fehler.

REST

REST verwendet Hypertext-Transfer-Protocol-Statuscodes (HTTP) mit der durch RFC 9110 definierten Semantik. Ein 200 liefert das Ergebnis; ein 400 wird zurückgegeben, wenn ein Anfragefeld die Formatvalidierung nicht besteht; ein 401 wird zurückgegeben, wenn kein gültiger API-Schlüssel vorgelegt wird, und trägt einen WWW-Authenticate: Bearer-Challenge-Header; ein 403 wird zurückgegeben, wenn die Stufe eines gültigen Schlüssels nicht zur Operation berechtigt ist; ein 404 wird zurückgegeben, wenn eine stufengesteuerte Route nicht registriert ist, weil ihr Paket fehlt. Maschinenlesbare Fehler-Bodies sind Problem-Details-Dokumente gemäß RFC 9457; sie werden mit dem Medientyp application/problem+json und einem stabilen type-Uniform-Resource-Identifier (URI) je Bedingung bereitgestellt. Validierungsfehler auf Feldebene werden im Body aufgeführt. Als Härtungsmaßnahme gegen Path Traversal wird eine document_id, die nicht dem Muster doc_[a-f0-9]{24} entspricht, mit 400 zurückgewiesen, bevor das Tool ausgeführt wird. Die REST-Middleware-Pipeline und die Routentabelle sind unter REST-Transport dokumentiert.

gRPC

gRPC verwendet die standardmäßigen gRPC-Statuscodes. Ein fehlendes, fehlerhaftes, unbekanntes, deaktiviertes oder abgelaufenes Token lässt den Aufruf mit UNAUTHENTICATED statt mit einem HTTP-Status fehlschlagen. Detaillierte Fehlerinformationen spiegeln die REST-Problem-Details-Form wider und werden in den gRPC-Status-Details mitgeführt, sodass der Fehler-type-URI über alle Transporte hinweg konsistent ist.

Siehe auch: RFC 9110 (HTTP Semantics) für die Statuscode-Semantik und RFC 9457 (Problem Details for HTTP APIs) für das Format des Fehlerbodies.

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

Ratenlimits und Kontingente

Der REST-Transport wendet in seiner Middleware-Pipeline Rate-Limiting pro Internet-Protocol-Adresse (pro IP) und pro Client an, dazu Body-Größen- und Stufen-Payload-Limits sowie einen Timeout pro Anfrage. Die relevanten Obergrenzen sind Konfigurationswerte, keine festcodierten Konstanten:

• Stufenbezogene Payload-Obergrenzen (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) und die passenden Timeouts gelten bei REST entsprechend der Stufe des authentifizierten Schlüssels. Siehe Konfiguration.
• Der In-Memory-Dokumentspeicher ist durch max_documents (Standard 50) und document_ttl (Standard 1800 Sekunden) begrenzt.
• Der Zustand für Rate-Limiting und Idempotenz ist pro Worker, sofern nicht NEXTPDF_REDIS_HOST für einen gemeinsamen Speicher konfiguriert ist. Siehe Deployment.

Wenn die Speicher für Rate-Limiting und Idempotenz gemeinsam genutzt werden, werden wiederholte identische asynchrone Job-Einreichungen anhand des idempotency_key dedupliziert. Der MCP-Transport bearbeitet jeweils eine Anfrage über Pipes und dedupliziert eine wiederholte Anfrage-id aus einem Puffer mit 64 Einträgen, anstatt Netzwerk-Ratenlimits anzuwenden.

Entwicklungshinweise

• Lesen Sie Tool-Namen, Klassen und Risikostufen aus dem Quellcode unter src/Tools/; gehen Sie nicht von einer festen Gesamtzahl aus. Fragen Sie den laufenden Server nach der maßgeblichen Anzahl ab, wie auf Tool-Katalog gezeigt.
• Generieren Sie die gRPC-Client-Stubs aus den ausgelieferten proto/nextpdf/connect/v1/*.proto-Dateien neu; Paket und Namespace lauten nextpdf.connect.v1. Bearbeiten Sie generierte Nachrichtenklassen nicht von Hand.
• Ein ApprovalRequired-Tool antwortet beim ersten Aufruf mit einer Bestätigungs-Challenge. Implementieren Sie den Retry-Pfad — leiten Sie die Challenge weiter und rufen Sie dann erneut mit _confirmation_token auf —, bevor Sie eine Integration ausliefern, die output_pdf oder ein beliebiges Mutations-Tool ansteuert.
• Eine stufengesteuerte Route oder Capability, die nicht installiert ist, ist kein Authentifizierungsfehler: REST gibt 404 für eine fehlende Route zurück, und gRPC ExecuteCapability meldet die Operation als nicht verfügbar. Behandeln Sie eine fehlende Pro- oder Enterprise-Stufe als erwartetes Verhalten, nicht als Fehler.
• Halten Sie API-Schlüssel aus der Versionsverwaltung heraus; mounten Sie sie aus einer Secret-Datei und bevorzugen Sie den Datei-Schlüsselspeicher mit Hot Reload, sodass eine Rotation keinen Neustart erfordert. Siehe Sicherheit und Betrieb.

Siehe auch

• Entwicklerhandbuch — Architektur, Lebenszyklus, Erweiterungspunkte und die Test-Checkliste
• Tool-Katalog — das verifizierte Kern-Tool-Set und die Laufzeitanzahl
• HITL-Risikostufen — das Risikomodell und die Bestätigungs-Challenge
• MCP-Transport · REST-Transport · gRPC-Transport — Wire-Details pro Transport
• Sicherheit und Betrieb — Authentifizierung, Transportsicherheit und das Bedrohungsmodell