NextPDF Connect API-referentie
In het kort
Sectie met titel “In het kort”Deze pagina is de symboolreferentie voor de NextPDF Connect-server (nextpdf/server). Je vindt hier elke tool met de geregistreerde toolnaam en implementatieklasse, plus de gRPC-service NextPDFConnect, inclusief de Remote Procedure Call (RPC)-methoden en de aanvraag- en antwoordberichten. De pagina definieert ook het authenticatie-, fout- en rate-limit-contract dat alle transporten delen.
De server biedt één toolregister aan via drie transporten: Model Context Protocol (MCP) over standaardinvoer en -uitvoer, een Representational State Transfer (REST) Application Programming Interface (API), en gRPC. Elk transport documenteert zijn protocoldetails op een aparte pagina: zie MCP-transport, REST-transport en gRPC-transport. Deze pagina catalogiseert de symbolen die deze transporten gebruiken.
Toolnamen, klassen en risiconiveaus worden gelezen uit de toolimplementaties in src/Tools/. Het aantal tools dat een implementatie aanbiedt, is een runtime-eigenschap; zie Toolcatalogus. Boot en discovery legt de niveaubepaling uit.
Beschikbaarheid per transport
Sectie met titel “Beschikbaarheid per transport”Een tool is beschikbaar via elk transport waarop de implementatie draait. Transporten draaien als onafhankelijke processen; als je het ene start, start je het andere niet automatisch.
| Transport | Toegangspunt | Protocolformaat | Authenticatie |
|---|---|---|---|
| MCP | bin/nextpdf-mcp | JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 over stdio | Procesgrens van het besturingssysteem (geen API-sleutel) |
| REST | bin/nextpdf-server | HTTP, OpenAPI 3.1 | Bearer API-sleutel in de Authorization-header |
| gRPC | bin/nextpdf-grpc | Protocol Buffers, package nextpdf.connect.v1 | Bearer-token in de authorization-aanroepmetadata |
Via MCP roep je een tool aan met tools/call en de geregistreerde toolnaam. Via REST en gRPC bereik je dezelfde engine-mogelijkheden via de render-, operatie- en capability-oppervlakken; zie de routetabel van het REST-transport en de RPC-tabel van het gRPC-transport.
Authenticatie en risiconiveau
Sectie met titel “Authenticatie en risiconiveau”API-sleutelauthenticatie
Sectie met titel “API-sleutelauthenticatie”De REST- en gRPC-transporten vereisen bij elke aanvraag een bearer API-sleutel, behalve bij niet-geauthenticeerde health-probes. Een sleutel heeft de vorm npk_live_{kid}_{secret}: de kid is een identificator van acht tekens om records op te zoeken, en het secret levert de entropie. De server slaat alleen een SHA-256-digest van de sleutel op en vergelijkt het aangeboden token in constante tijd, zodat een ongeldige sleutel niets prijsgeeft via timing. REST leest het token uit de Authorization: Bearer …-header; gRPC leest hetzelfde token uit de authorization-aanroepmetadata. Het MCP-stdio-transport heeft geen API-sleutel, omdat het een lokaal subproces is dat door de startende client wordt vertrouwd. Beveiliging en operaties documenteert het volledige authenticatiemodel.
De vier risiconiveaus
Sectie met titel “De vier risiconiveaus”Elke tool declareert een van vier geordende risiconiveaus, gedefinieerd door de RiskLevel-enum in src/Config/RiskLevel.php.
| Niveau | Enum-case | Waarde | Effect |
|---|---|---|---|
| Safe | RiskLevel::Safe | 0 | Alleen-lezen, geen neveneffecten. Voert automatisch uit. |
| Caution | RiskLevel::Caution | 1 | Maakt of wijzigt in-memory state. Voert automatisch uit, met auditlog. |
| Review | RiskLevel::Review | 2 | Produceert uitvoer die misbruikt kan worden. Voert automatisch uit, met auditlog. |
| ApprovalRequired | RiskLevel::ApprovalRequired | 3 | Destructief, juridisch of privacykritisch. Vereist menselijke bevestiging. |
Het effectieve risico van een tool komt uit precies twee bronnen: de eigen riskLevel()-declaratie van de tool, en een optionele beheerdersconfiguratie-override die het risico alleen mag verhogen en een ApprovalRequired-tool nooit mag verlagen. Zie HITL-risiconiveaus en Configuratie.
Hoe goedkeuringstokens stromen
Sectie met titel “Hoe goedkeuringstokens stromen”Wanneer je een ApprovalRequired-tool aanroept zonder geldig token, retourneert de ConfirmationGate (src/Mcp/ConfirmationGate.php) een eenmalig challenge-token in plaats van de tool uit te voeren. De agent geeft de challenge door aan een mens en roept daarna dezelfde tool opnieuw aan met het uitgegeven token in het argument _confirmation_token. Het token bindt de toolnaam, een willekeurige nonce en een time-to-live (TTL) van 300 seconden. Het bindt de argumenten niet en is geen authenticatiegegeven. Bij REST authenticeert de bearer API-sleutel de aanvraag nog steeds, en dezelfde gate draait in de gedeelde tool-executor vóór de gegate operatie. Bij gRPC draait dezelfde gate vóór de verzonden operatie. Het challenge- en tokenmechanisme is voor alle transporten identiek.
Tools en endpoints
Sectie met titel “Tools en endpoints”De tabel documenteert elke tool aan de hand van de geregistreerde toolnaam (kolom Symbool) en implementatieklasse. Tools zijn gegroepeerd per niveau en categorie. Alle Abstract Syntax Tree (AST)- en mutatieklassen bevinden zich onder src/Tools/Ast en src/Tools/Ast/Mutation; de extractieklasse bevindt zich onder src/Tools/Extraction; de overige klassen bevinden zich onder src/Tools/Core.
Kerndocumenttools
Sectie met titel “Kerndocumenttools”| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of faalt met | Opmerkingen |
|---|---|---|---|---|---|
create_pdf | page_size (standaard A4), orientation (portrait/landscape), title, author; geen verplicht. | Maakt een in-memory document en een pagina aan; stelt metadata in als die is opgegeven. | JSON met document_id, page_count, page_size, orientation. | Retourneert bij een fout een foutresultaat met het bericht van de engine. | Klasse CreatePdfTool. Risico RiskLevel::Caution. Niveau core. De geretourneerde document_id wordt gebruikt voor elke volgende operatie. |
add_page | document_id (verplicht), optioneel paginaformaat en oriëntatie. | Voegt een pagina toe aan het document. | JSON met het nieuwe paginaaantal. | Foutresultaat wanneer document_id onbekend is. | Klasse AddPageTool. Risico RiskLevel::Caution. Niveau core. |
add_text | document_id (verplicht), text (verplicht), optioneel positie en stijl. | Voegt tekst toe aan het document. | JSON-samenvatting van de documentstatus. | Foutresultaat wanneer document_id onbekend is. | Klasse AddTextTool. Risico RiskLevel::Caution. Niveau core. |
add_image | document_id (verplicht), source (verplicht: bestandspad of base64), optioneel plaatsing. | Voegt een afbeelding toe vanuit een pad of base64-gegevens. | JSON-samenvatting van de documentstatus. | Foutresultaat bij een onleesbare bron of een onbekende document_id. | Klasse AddImageTool. Risico RiskLevel::Caution. Niveau core. |
add_table | document_id (verplicht), html (verplicht). | Rendert een Hypertext Markup Language (HTML)-tabel in het document. | JSON-samenvatting van de documentstatus. | Foutresultaat bij ongeldige markup of een onbekende document_id. | Klasse AddTableTool. Risico RiskLevel::Caution. Niveau core. |
set_font | document_id (verplicht), family (verplicht), optioneel grootte en stijl. | Stelt het lettertype in voor volgende tekstoperaties. | JSON-bevestiging van het actieve lettertype. | Foutresultaat bij een onbekend lettertype of document_id. | Klasse SetFontTool. Risico RiskLevel::Caution. Niveau core. |
output_pdf | document_id (verplicht), file_path (optioneel), destroy (standaard true). | Finaliseert het document; schrijft naar file_path, of retourneert base64 als dit is weggelaten; vernietigt het document standaard. | JSON met file_path en file_size, of base64 en file_size. | Foutresultaat wanneer document_id onbekend is; mislukte padinsluiting bij schrijven buiten de basismap. | Klasse OutputPdfTool. Risico RiskLevel::ApprovalRequired. Niveau core. Het schrijven van een bestand passeert de bevestigingsgate; de base64-modus niet. |
preview_layout | document_id (verplicht). | Retourneert een lay-outsamenvatting zonder de definitieve PDF te renderen. | JSON-lay-outsamenvatting. | Foutresultaat wanneer document_id onbekend is. | Klasse PreviewLayoutTool. Risico RiskLevel::Safe. Niveau core. |
parse_pdf | document_id (verplicht). | Inspecteert structurele metadata: paginaaantal, lettertypen, afbeeldingen, versleuteling en Info Dictionary. | JSON met structurele metadata. | Foutresultaat bij een misvormd document. | Klasse ParsePdfTool. Risico RiskLevel::Safe. Niveau core. Wordt alleen geregistreerd wanneer NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED gelijk is aan true of 1. |
Kerndiagnosetools
Sectie met titel “Kerndiagnosetools”| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of faalt met | Opmerkingen |
|---|---|---|---|---|---|
diagnostic.doctor | geen. | Voert een health check uit en retourneert gestructureerde omgevingsdiagnostiek. | JSON-omgevingsrapport. | Foutresultaat bij een interne controlefout. | Klasse DiagnosticDoctorTool. Risico RiskLevel::Safe. Niveau core. Vereist geen document en geen bevestiging. |
diagnostic.capabilities | geen. | Geeft een overzicht van capabilities met niveau- en statusinformatie. | JSON-capabilitylijst. | Foutresultaat bij een interne fout. | Klasse DiagnosticCapabilitiesTool. Risico RiskLevel::Safe. Niveau core. |
diagnostic.inspect | document_id (verplicht). | Inspecteert een PDF en retourneert structurele metadata. | JSON met structurele metadata. | Foutresultaat wanneer document_id onbekend is. | Klasse DiagnosticInspectTool. Risico RiskLevel::Safe. Niveau core. |
diagnostic.verify | document_id (verplicht), optioneel PDF/A- of PDF/UA-profiel. | Verifieert de structurele integriteit; valideert optioneel PDF/A of PDF/UA door een VeraPDF-subproces te starten. | JSON-verificatierapport op niveau. | Foutresultaat bij een subprocesfout, time-out of te grote invoer. | Klasse DiagnosticVerifyTool. Risico RiskLevel::Caution. Niveau core. De invoer is begrensd op 50 mebibytes (MiB). |
Kernbarcodetool
Sectie met titel “Kernbarcodetool”| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of faalt met | Opmerkingen |
|---|---|---|---|---|---|
generate_barcode | payload (verplicht), format (bijvoorbeeld QR Code, DataMatrix). | Genereert een tweedimensionale barcode-modulematrix voor de payload. | JSON-modulematrix. | Foutresultaat bij een niet-ondersteund format of een ongeldige payload. | Klasse BarcodeTool. Risico RiskLevel::Caution. Niveau core. BarcodeTool wordt alleen geregistreerd wanneer het core-barcode-encoderregister aanwezig is in de geïnstalleerde nextpdf/core; de geregistreerde toolnaam is generate_barcode. |
Enterprise-privacytools
Sectie met titel “Enterprise-privacytools”Deze tools omhullen Enterprise-privacyklassen en worden alleen onder het Enterprise-niveau geregistreerd wanneer die klassen autoloadbaar zijn. Ze werken op platte-tekstinhoud.
| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of faalt met | Opmerkingen |
|---|---|---|---|---|---|
redact_pdf | content (verplicht), optionele detectieopties. | Redigeert destructief persoonlijk identificeerbare informatie (PII) in platte-tekstinhoud met behulp van de Enterprise-redactie-engine. | JSON met de geredigeerde inhoud en een SHA-256-hash. | Foutresultaat wanneer de Enterprise-klassen ontbreken of de detectie mislukt. | Klasse RedactPdfTool. Risico RiskLevel::Review. Niveau enterprise. |
deidentify_pdf | content (verplicht), strategy (redact of suppress). | Past een systematische de-identificatiestrategie toe op platte-tekstinhoud met behulp van de Enterprise-de-identifier. | JSON met de gede-identificeerde inhoud. | Foutresultaat wanneer de Enterprise-klassen ontbreken. | Klasse DeIdentifyPdfTool. Risico RiskLevel::Review. Niveau enterprise. |
zone_redact_pdf | content (verplicht), zones (pagina plus lijst met genormaliseerde rechthoeken). | Past coördinaatgebaseerde zoneredacties toe met behulp van de Enterprise-redactie-engine. | JSON met de geredigeerde inhoud. | Foutresultaat bij een ongeldige zone of ontbrekende Enterprise-klassen. | Klasse ZoneRedactionTool. Risico RiskLevel::Review. Niveau enterprise. |
Abstract syntax tree (AST)-leestools
Sectie met titel “Abstract syntax tree (AST)-leestools”Deze tools worden met de server meegeleverd, worden onder het Pro-niveau geregistreerd en zijn gegated door NEXTPDF_AST_TOOLS_ENABLED (standaard ingeschakeld). Ze zijn alleen-lezen.
| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of faalt met | Opmerkingen |
|---|---|---|---|---|---|
get_document_ast | pdf_data (verplicht). | Bouwt een semantische AST: een volledige knooppuntboom met citatieankers voor elk structureel element. | JSON-knooppuntboom plus een ETag voor concurrency-controle. | Foutresultaat bij een misvormd document. | Klasse GetDocumentAstTool. Risico RiskLevel::Safe. Niveau pro. |
get_ast_node | pdf_data (verplicht), node_id (verplicht). | Haalt één AST-knooppunt en al zijn kinderen op. | JSON-knooppunt met kinderen. | Foutresultaat bij een onbekende node_id. | Klasse GetAstNodeTool. Risico RiskLevel::Safe. Niveau pro. |
get_ast_diff | original_pdf_data (verplicht), modified_pdf_data (verplicht). | Vergelijkt twee documenten structureel door hun semantische AST’s te vergelijken. | JSON met toegevoegde, verwijderde en gewijzigde knooppunten. | Foutresultaat bij een misvormd invoerdocument. | Klasse GetAstDiffTool. Risico RiskLevel::Safe. Niveau pro. |
search_ast_nodes | pdf_data (verplicht), optionele type-, paginaindex- en tekstfilters. | Doorzoekt AST-knooppunten op type, paginaindex of tekstinhoud. | JSON met een platte lijst van overeenkomende knooppunten met ondiepe kinderen. | Foutresultaat bij een misvormd document. | Klasse SearchAstNodesTool. Risico RiskLevel::Safe. Niveau pro. |
extract_cited_text | pdf_data (verplicht), optioneel headings_only. | Extraheert tekstblokken met citatieankers (pagina, omkaderend kader, vertrouwen). | JSON met geciteerde tekstblokken. | Foutresultaat bij een misvormd document. | Klasse ExtractCitedTextTool. Risico RiskLevel::Safe. Niveau pro. Categorie ast. |
extract_cited_tables | pdf_data (verplicht). | Extraheert tabelblokken met citatieankers; retourneert per Table-knooppunt een rijgewijze matrix van cellen. | JSON met tabelmatrices met ankers. | Foutresultaat bij een misvormd document. | Klasse ExtractCitedTablesTool. Risico RiskLevel::Safe. Niveau pro. Categorie extraction. |
AST-mutatietools
Sectie met titel “AST-mutatietools”Deze tools worden met de server meegeleverd, worden onder het Pro-niveau geregistreerd en zijn gegated door NEXTPDF_MUTATION_TOOLS_ENABLED (standaard ingeschakeld). Alle vier zijn ApprovalRequired en gebruiken optimistic concurrency control (OCC) via een ETag.
| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of faalt met | Opmerkingen |
|---|---|---|---|---|---|
apply_ast_mutations | pdf_data, etag, idempotency_key, mutations (alle verplicht). | Past een batch mutaties atomair toe; speelt het gecachte resultaat opnieuw af voor een herhaalde idempotency_key. | JSON met de gemuteerde PDF en een nieuwe ETag. | OCC-conflict wanneer de ETag verouderd is; validatiefout bij een misvormde mutatie. | Klasse ApplyAstMutationsTool. Risico RiskLevel::ApprovalRequired. Niveau pro. |
delete_ast_node | pdf_data, node_id, etag (alle verplicht). | Verwijdert een knooppunt in overlaymodus (de oorspronkelijke inhoud wordt afgedekt, niet fysiek verwijderd). | JSON met de gewijzigde PDF en een nieuwe ETag. | OCC-conflict wanneer de ETag verouderd is; fout bij een onbekende node_id. | Klasse DeleteAstNodeTool. Risico RiskLevel::ApprovalRequired. Niveau pro. |
insert_ast_node | pdf_data, parent_node_id, position, etag, node (alle verplicht). | Voegt op de opgegeven positie een nieuw knooppunt in als kind van de ouder. | JSON met de gewijzigde PDF en een nieuwe ETag. | OCC-conflict wanneer de ETag verouderd is; validatiefout bij een misvormd knooppunt. | Klasse InsertAstNodeTool. Risico RiskLevel::ApprovalRequired. Niveau pro. |
update_ast_node | pdf_data, node_id, etag, updates (alle verplicht). | Werkt de tekstinhoud van een knooppunt bij. | JSON met de gewijzigde PDF en een nieuwe ETag. | OCC-conflict wanneer de ETag verouderd is; fout bij een onbekende node_id. | Klasse UpdateAstNodeTool. Risico RiskLevel::ApprovalRequired. Niveau pro. |
Aanvraag- en antwoordschema
Sectie met titel “Aanvraag- en antwoordschema”Het gRPC-transport definieert het getypeerde schema van de server in de Protocol Buffers-package nextpdf.connect.v1, in proto/nextpdf/connect/v1/*.proto. De service en de bijbehorende berichten zijn de canonieke schemasymbolen.
Service NextPDFConnect
Sectie met titel “Service NextPDFConnect”De service NextPDFConnect biedt unaire en server-streaming RPC’s. De schemasymbolen zijn de RPC-methodenamen en de aanvraag- en antwoordberichten die ze dragen.
| RPC | Aanvraagbericht | Antwoordbericht | Vorm |
|---|---|---|---|
Render | RenderRequest | RenderResponse | Unair. Synchrone stateless render. |
RenderStream | RenderRequest | RenderChunk (stream) | Server-streaming. Render wordt geleverd als geordende chunks. |
SubmitJob | SubmitJobRequest | JobResponse | Unair. Dient een asynchrone renderjob in. |
GetJobStatus | GetJobStatusRequest | JobResponse | Unair. Polt de jobstatus. |
GetJobResult | GetJobResultRequest | RenderResponse | Unair. Download een voltooid resultaat. |
GetJobResultStream | GetJobResultRequest | RenderChunk (stream) | Server-streaming. Download een voltooid resultaat als chunks. |
CancelJob | CancelJobRequest | JobResponse | Unair. Annuleert of verwijdert een job. |
CreateSession | CreateSessionRequest | SessionResponse | Unair. Maakt een document-bouwsessie aan. |
GetSession | GetSessionRequest | SessionResponse | Unair. Haalt sessiemetadata op. |
DestroySession | DestroySessionRequest | DestroySessionResponse | Unair. Vernietigt een sessie en het bijbehorende document. |
SessionOperation | SessionOperationRequest | SessionResponse | Unair. Voert een operatie uit op een sessiedocument. |
SessionRender | SessionRenderRequest | RenderResponse | Unair. Rendert een sessiedocument naar PDF. |
SessionRenderStream | SessionRenderRequest | RenderChunk (stream) | Server-streaming. Rendert een sessiedocument als chunks. |
ExecuteCapability | CapabilityRequest | CapabilityResponse | Unair. Voert een niveaugegate capability-operatie uit. |
GetCapabilities | GetCapabilitiesRequest | GetCapabilitiesResponse | Unair. Geeft de capabilities voor de geauthenticeerde client weer. |
HealthCheck | HealthCheckRequest | HealthCheckResponse | Unair. Liveness-probe. |
ReadinessCheck | ReadinessCheckRequest | ReadinessCheckResponse | Unair. Readiness-probe. |
Berichtsymbolen
Sectie met titel “Berichtsymbolen”De aanvraag- en antwoordberichten zijn de structurele symbolen van het schema. De renderberichten, RenderRequest, RenderResponse en de streaming RenderChunk, dragen het paginaformaat, de oriëntatie, de geordende operaties en de resulterende PDF-bytes. De jobberichten, SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest en JobResponse, modelleren de asynchrone joblevenscyclus, waarbij jobmetadata in het bericht JobData staat. De sessieberichten, CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest en SessionRenderRequest, modelleren de stateful sessielevenscyclus, waarbij sessiemetadata in het bericht SessionData staat. De capabilityberichten, CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest en GetCapabilitiesResponse, dragen niveaugegate operatiedispatch en introspectie. De systeemberichten, HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest en ReadinessCheckResponse, dragen liveness- en readiness-status.
De meegeleverde .proto-bestanden zijn het gezaghebbende wire-contract; zie de gRPC-transportreferentie op gRPC-transport.
Foutmodel
Sectie met titel “Foutmodel”De server rapporteert fouten met het native foutmechanisme van elk transport. Elk transport behoudt dezelfde logische conditie; alleen de codering verschilt.
MCP-fouten zijn JSON-RPC 2.0-foutobjecten. Een onbekende methode retourneert method-not-found (-32601); een bericht dat geen geldige JSON-RPC is, retourneert invalid-request (-32600); niet-parseerbare invoer retourneert parse-error (-32700). Een falende tool retourneert een succesvol JSON-RPC-antwoord waarvan de inhoud de fout markeert, in plaats van een fout op transportniveau, zodat de agent het bericht kan lezen. Een bevestigingschallenge voor een ApprovalRequired-tool is ook een succesvol antwoord, geen fout.
REST gebruikt Hypertext Transfer Protocol (HTTP)-statuscodes met de semantiek die RFC 9110 definieert. Een 200 draagt het resultaat; een 400 wordt geretourneerd wanneer een aanvraagveld niet door de formaatvalidatie komt; een 401 wordt geretourneerd wanneer geen geldige API-sleutel wordt aangeboden en draagt een WWW-Authenticate: Bearer-challenge-header; een 403 wordt geretourneerd wanneer het niveau van een geldige sleutel geen recht geeft op de operatie; een 404 wordt geretourneerd wanneer een niveaugegate route niet is geregistreerd omdat het bijbehorende package ontbreekt. Machineleesbare foutlichamen zijn Problem Details-documenten volgens RFC 9457, geserveerd met het mediatype application/problem+json en een stabiele type Uniform Resource Identifier (URI) voor elke conditie. Validatiefouten op veldniveau worden in het lichaam opgesomd. Als hardeningsmaatregel tegen path traversal wordt een document_id die niet overeenkomt met het patroon doc_[a-f0-9]{24} afgewezen met 400 voordat de tool wordt uitgevoerd. REST-transport documenteert de REST-middlewarepijplijn en de routetabel.
gRPC gebruikt standaard gRPC-statuscodes. Bij een ontbrekend, misvormd, onbekend, uitgeschakeld of verlopen token faalt de aanroep met UNAUTHENTICATED in plaats van een HTTP-status. Rijke foutdetails volgen de vorm van de REST Problem Details en worden in de gRPC-statusdetails meegestuurd, zodat de fout-type-URI consistent is over alle transporten.
Zie ook RFC 9110 (HTTP Semantics) voor de semantiek van statuscodes en RFC 9457 (Problem Details for HTTP APIs) voor het formaat van het foutlichaam.
- RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
- RFC 9457: https://www.rfc-editor.org/rfc/rfc9457
Rate limits en quota’s
Sectie met titel “Rate limits en quota’s”Het REST-transport past in zijn middlewarepijplijn rate limiting per Internet-Protocol-adres (per-IP) en per client toe, plus limieten voor bodygrootte en payload per niveau en een time-out per aanvraag. Deze plafonds zijn configuratiewaarden, geen hard-gecodeerde constanten:
- Payloadplafonds per niveau (
corePayloadLimit,proPayloadLimit,enterprisePayloadLimit) en de bijbehorende time-outs gelden voor REST volgens het niveau van de geauthenticeerde sleutel. Zie Configuratie. - De in-memory documentstore wordt begrensd door
max_documents(standaard 50) endocument_ttl(standaard 1800 seconden). - Rate-limit- en idempotency-state is per worker, tenzij
NEXTPDF_REDIS_HOSTis geconfigureerd voor een gedeelde store. Zie Implementatie.
Wanneer de rate-limit- en idempotency-stores gedeeld zijn, worden herhaalde identieke asynchrone jobinzendingen ontdubbeld op basis van de idempotency_key. Het MCP-transport verwerkt één aanvraag tegelijk over pipes en ontdubbelt een herhaalde aanvraag-id uit een buffer met 64 vermeldingen, in plaats van netwerk-rate-limits toe te passen.
Ontwikkelnotities
Sectie met titel “Ontwikkelnotities”- Lees toolnamen, klassen en risiconiveaus uit de broncode onder
src/Tools/; ga niet uit van een vast totaal. Vraag de draaiende server om het gezaghebbende aantal, zoals getoond in Toolcatalogus. - Regenereer gRPC-clientstubs uit de meegeleverde
proto/nextpdf/connect/v1/*.proto-bestanden; de package en namespace zijnnextpdf.connect.v1. Bewerk gegenereerde berichtklassen niet handmatig. - Een
ApprovalRequired-tool antwoordt bij de eerste aanroep met een bevestigingschallenge. Bouw het herhaalpad — geef de challenge door en roep daarna opnieuw aan met_confirmation_token— voordat je een integratie uitlevert dieoutput_pdfof een mutatietool aanstuurt. - Een niveaugegate route of capability die niet is geïnstalleerd, is geen authenticatiefout: REST retourneert
404voor een afwezige route, en gRPCExecuteCapabilityrapporteert de operatie als niet beschikbaar. Behandel een afwezig Pro- of Enterprise-niveau als verwacht gedrag, niet als een fout. - Houd API-sleutels buiten versiebeheer; koppel ze vanuit een secret-bestand en geef de voorkeur aan de hot-reloading bestandssleutelstore, zodat rotatie geen herstart vereist. Zie Beveiliging en operaties.
Zie ook
Sectie met titel “Zie ook”- Ontwikkelaarsgids — architectuur, levenscyclus, uitbreidingspunten en de testchecklist
- Toolcatalogus — de geverifieerde core-toolset en het runtime-aantal
- HITL-risiconiveaus — het risicomodel en de bevestigingschallenge
- MCP-transport · REST-transport · gRPC-transport — protocoldetail per transport
- Beveiliging en operaties — authenticatie, transportbeveiliging en het dreigingsmodel