Connect REST API-referentie

In het kort

NextPDF Connect stelt zijn toolregister via HTTP beschikbaar als een REST-transport, beschreven door een OpenAPI 3.1-contract. Deze pagina is de referentie voor dat oppervlak: de basis-URL, hoe je je authenticeert, de bewerkingsgroepen en het foutmodel. De volledige machineleesbare specificatie wordt gepubliceerd zodat je die in een interactieve verkenner, een clientgenerator of een request-client kunt laden zonder iets handmatig te kopiëren.

Voor de transportonafhankelijke toolcatalogus (dezelfde bewerkingen via het Model Context Protocol, gRPC en REST), zie de Connect API-referentie. Voor de RoadRunner-pijplijn, deployment en authenticatieconfiguratie, zie de REST-transportgids.

Basis-URL en authenticatie

Het REST-transport luistert op de host en poort die voor je deployment zijn geconfigureerd. Lokaal is dat http://localhost:8080; in productie is het het adres vóór je worker-pool.

Authenticatie verloopt via een bearer-token. Stuur de API-sleutel mee in de Authorization-header bij elke aanvraag naar een route die per niveau is beveiligd:

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

Liveness- en readiness-probes die alleen lezen, vereisen geen token.

Bewerkingen

De beschikbaarheid is per niveau beveiligd. De open-sourcekern levert de bewerkingen voor documenten, rendering, sessies en jobs. Ondertekenen, formulieren invullen, redigeren, vergelijken, toegankelijkheidscontrole en optimalisatie vereisen een commerciële editie die naast de server is geïnstalleerd. De gezaghebbende set voor een specifieke deployment wordt geretourneerd door het capabilities-endpoint. Vraag dit endpoint op in plaats van uit te gaan van een vaste lijst.

Gezondheid en levenscyclus

Methode	Pad	Doel
GET	/healthz	Liveness-probe. Geen authenticatie.
GET	/readyz	Readiness-probe (afhankelijkheden en worker-pool gereed). Geen authenticatie.
GET	/api/v1/capabilities	De tools en niveaus die deze deployment daadwerkelijk beschikbaar stelt. Vraag dit endpoint eerst op.

Rendering en documenten

Methode	Pad	Doel
POST	/api/v1/render	Render een document op basis van een geordende lijst met bewerkingen en retourneer de PDF.
POST	/api/v1/extract-text	Extraheer tekstinhoud uit een PDF.
POST	/api/v1/merge	Voeg meerdere PDF-invoerbestanden samen tot één document.
POST	/api/v1/split	Splits een PDF in meerdere documenten.

Asynchrone jobs

Methode	Pad	Doel
POST	/api/v1/jobs	Dien een langlopende bewerking in als een job.
GET	/api/v1/jobs/{id}	Vraag de jobstatus op.
GET	/api/v1/jobs/{id}/result	Haal het voltooide jobresultaat op.

Sessies

Sessies houden een document over meerdere aanroepen heen open, zodat je het stapsgewijs kunt opbouwen en aan het einde eenmalig kunt renderen.

Methode	Pad	Doel
POST	/api/v1/sessions	Open een sessie.
GET / DELETE	/api/v1/sessions/{sessionId}	Inspecteer of sluit een sessie.
POST	/api/v1/sessions/{sessionId}/pages	Voeg een pagina toe.
POST	/api/v1/sessions/{sessionId}/text	Voeg tekst toe.
POST	/api/v1/sessions/{sessionId}/images	Voeg een afbeelding toe.
POST	/api/v1/sessions/{sessionId}/tables	Voeg een tabel toe.
POST	/api/v1/sessions/{sessionId}/html	Voeg gerenderde HTML toe.
POST	/api/v1/sessions/{sessionId}/font	Stel het actieve lettertype in.
POST	/api/v1/sessions/{sessionId}/render	Render het sessiedocument.

Bewerkingen van de commerciële editie

Deze routes worden alleen geregistreerd wanneer de bijbehorende commerciële editie is geïnstalleerd. Voor verschillende routes is goedkeuring vereist via de human-in-the-loop-bevestigingsflow; zie risiconiveaus.

Methode	Pad	Doel
POST	/api/v1/sign	Pas een digitale handtekening toe.
POST	/api/v1/fill-form	Vul een interactief formulier in.
POST	/api/v1/redact	Redigeer inhoud.
POST	/api/v1/compare	Vergelijk twee PDF-documenten.
POST	/api/v1/check-accessibility	Voer een structurele toegankelijkheidscontrole uit.
POST	/api/v1/optimize	Optimaliseer en verklein een document.

Foutmodel

Het REST-transport gebruikt HTTP-statuscodes met de semantiek die is gedefinieerd door RFC 9110: 2xx voor succes, 4xx voor een aanvraag die de aanroeper moet corrigeren (400 onjuist gevormde body, 401 ontbrekend of ongeldig token, 403 niveau of goedkeuring geweigerd, 404 onbekende route of job, 409 idempotentieconflict, 422 een correct gevormde aanvraag die de engine niet kan verwerken), en 5xx voor een serverfout. Een 401-respons bevat een WWW-Authenticate-challenge.

Foutbodies zijn application/problem+json-documenten conform RFC 9457 (Problem Details for HTTP APIs): een stabiel type, een korte title, de numerieke status en een voor mensen leesbare detail. Match op type, niet op de detail-string. Zie ook RFC 9110 (HTTP Semantics) en RFC 9457 voor de normatieve definities.

Dien statuswijzigende aanvragen in met een Idempotency-Key-header, zodat een opnieuw verzonden aanvraag eenmalig wordt verwerkt.

Machineleesbare specificatie

Het volledige contract wordt gepubliceerd als een statisch OpenAPI 3.1-document:

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

Gebruik dit document als de enige bron van waarheid voor het REST-oppervlak:

1. Open de interactieve API-verkenner — een in-browser, zelfgehoste Scalar-referentie die uit dit contract is gegenereerd — om elke bewerking met de bijbehorende aanvraag- en responsschema’s te lezen en uit te proberen.
2. Importeer het in een request-client zoals Postman of Insomnia.
3. Genereer een getypeerde client voor je taal met een OpenAPI-generator.

Het document is een statisch contract dat vast is gekoppeld aan de pakketversie. Het wordt niet door een live endpoint geleverd, dus het blijft stabiel over deployments heen.

Zie ook

• Connect API-referentie — de volledige toolcatalogus over MCP, REST en gRPC.
• REST-transportgids — RoadRunner-pijplijn, bearer-authenticatie en niveau-routing.
• NextPDF Connect-overzicht — wat de server is en hoe je deze uitvoert.