PDF operations

POST /v1/pdf/bookmarks/read

Reads the outline of each PDF sent, keyed by file name.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	The PDF to work on. Several for merge.
outputFilename	string	No

Responses

Status	Meaning	Body
200	Per file name	object
400	The request is wrong	ErrorBody

POST /v1/pdf/bookmarks/write

Replaces the outline.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
bookmarks	JSON	Yes	JSON array of {title, page, children}.
files	file	Yes
outputFilename	string	No

Responses

Status	Meaning	Body
200	The PDF with its outline replaced	File
400	The request is wrong	ErrorBody

POST /v1/pdf/convert

PDFs to PDF/A or PDF/UA through LibreOffice, with the same post-processing fields as /v1/convert.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	One or more documents.
assets	files	No	Images (PNG, JPEG, GIF, SVG), stylesheets and fonts an HTML page names by file name, as in <img src="logo.png">. Every stylesheet applies to the whole page. Nothing is fetched from anywhere else.
htmlEngine	string	No	What turns HTML into PDF: fulgur (default), a layout engine with no browser and no network, or libreoffice.
landscape	boolean	No
merge	boolean	No	Merge several inputs into one PDF instead of returning a ZIP.
nativePageRanges	string	No
outputFilename	string	No
password	string	No	Opens a protected input.
pdfa	string	No	PDF/A level: PDF/A-1b, PDF/A-2b, PDF/A-3b, PDF/A-4.
pdfua	boolean	No	Export as PDF/UA.
to	string	No	Output format. Default pdf.

Responses

Status	Meaning	Body
200	The converted PDF, or a ZIP of them	File
204	Accepted; the result goes to the webhook
400	The request is wrong	ErrorBody
503	An engine is unavailable or the request timed out	ErrorBody

POST /v1/pdf/embed

Attaches files to a PDF.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	The PDF first, then the files to attach.
outputFilename	string	No

Responses

Status	Meaning	Body
200	The PDF with attachments	File
400	The request is wrong	ErrorBody

POST /v1/pdf/encrypt

Encrypts a PDF with AES-256.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	file	Yes	One PDF.
ownerPassword	string	Yes
outputFilename	string	No
userPassword	string	No

Responses

Status	Meaning	Body
200	The encrypted PDF	File
204	Accepted; the result goes to the webhook
400	The request is wrong	ErrorBody
503	An engine is unavailable or the request timed out	ErrorBody

POST /v1/pdf/factur-x

Embeds Factur-X invoice XML and marks the PDF for it.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	The PDF/A-3 invoice, then the Factur-X XML.
profile	string	Yes	MINIMUM, BASIC_WL, BASIC, EN16931 or EXTENDED.
outputFilename	string	No

Responses

Status	Meaning	Body
200	The Factur-X PDF	File
400	The request is wrong	ErrorBody

POST /v1/pdf/flatten

Flattens forms and annotations into the page content.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	The PDF to work on. Several for merge.
outputFilename	string	No

Responses

Status	Meaning	Body
200	The flattened PDF	File
400	The request is wrong	ErrorBody

POST /v1/pdf/merge

Merges PDFs in the order sent.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	Two or more PDFs, merged in order.
outputFilename	string	No

Responses

Status	Meaning	Body
200	The merged PDF	File
204	Accepted; the result goes to the webhook
400	The request is wrong	ErrorBody
503	An engine is unavailable or the request timed out	ErrorBody

POST /v1/pdf/metadata/read

Reads the metadata of each PDF sent, keyed by file name.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	The PDF to work on. Several for merge.
outputFilename	string	No

Responses

Status	Meaning	Body
200	Per file name	object
400	The request is wrong	ErrorBody

POST /v1/pdf/metadata/write

Writes metadata keys; existing keys not named are kept.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	file	Yes
metadata	JSON	Yes	JSON object of keys such as Title, Author, Subject, Keywords.
outputFilename	string	No

Responses

Status	Meaning	Body
200	The PDF with its metadata changed	File
400	The request is wrong	ErrorBody

POST /v1/pdf/optimize

Recompresses streams and drops unused objects.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	The PDF to work on. Several for merge.
outputFilename	string	No

Responses

Status	Meaning	Body
200	The smaller PDF	File
400	The request is wrong	ErrorBody

POST /v1/pdf/rotate

Rotates pages by 90, 180 or 270 degrees.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	file	Yes
rotation	string	Yes	90, 180 or 270.
outputFilename	string	No
pages	string	No	Page selection such as 1-3,5; all when empty.

Responses

Status	Meaning	Body
200	The rotated PDF	File
400	The request is wrong	ErrorBody

POST /v1/pdf/sign

Signs a PDF. With signature=certificate, a cryptographic signature with the key in RUSTICDOC_SIGNING_KEY and RUSTICDOC_SIGNING_CERT, or the named key signingKey chooses: an incremental update with a PAdES /ETSI.CAdES.detached signature at the level asked for (B-B to B-LTA), approving or, with certify, certifying. It is invisible, shown with the one image sent, or, with a position and no image, shown as text naming the signer, the date and the reason. Without a configured key that answers 503; a timestamp authority or revocation source that fails answers 502. By default (signature=image) the images are drawn at exact coordinates, which is not a cryptographic signature.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	The PDF first, then one PNG or JPEG per placement. With signature=certificate, at most one image: the visible appearance.
certify	integer	No	With signature=certificate: certify rather than approve, with this DocMDP permission: 1 no changes, 2 form filling and signing, 3 also annotations. Only the document’s first signature can certify.
contactInfo	string	No	With signature=certificate: how to reach the signer.
level	string	No	With signature=certificate: the PAdES level, b-b, b-t (with an RFC 3161 timestamp), b-lt (and validation data in a DSS) or b-lta (and a document timestamp). Default the service’s RUSTICDOC_SIGNING_LEVEL, b-b unless set.
location	string	No	With signature=certificate: where it was signed.
outputFilename	string	No
page	integer	No	1-based page of each image; repeat the field for several.
reason	string	No	With signature=certificate: why the document was signed.
signature	string	No	image (default) draws the images and is not a cryptographic signature. certificate signs with the service’s key (PAdES, /ETSI.CAdES.detached), invisibly unless an image or a position is sent.
signerName	string	No	With signature=certificate: the signer’s name as shown. Validators identify the signer by the certificate, not by this.
signingKey	string	No	With signature=certificate: a named key from RUSTICDOC_SIGNING_KEYS instead of the default one. A caller not on its allow list gets 403.
width	number	No	Width in points. Default the image’s natural size, or 200 for a text appearance.
x	number	No	Points from the page’s left edge to the image’s left edge.
y	number	No	Points from the page’s bottom edge to the image’s bottom edge.

Responses

Status	Meaning	Body
200	The signed PDF	File
204	Accepted; the result goes to the webhook
400	The request is wrong	ErrorBody
403	The caller may not use the signing key	ErrorBody
502	The timestamp authority or a revocation source failed	ErrorBody
503	signature=certificate and no signing key is configured, the level needs a timestamp authority that is not configured, or the certificate has expired	ErrorBody

POST /v1/pdf/split

Splits a PDF by page ranges or into fixed intervals; several outputs come back as a ZIP.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	file	Yes
splitMode	string	Yes	pages or intervals.
splitSpan	string	Yes	For pages: ranges such as 1-3,5. For intervals: pages per file.
outputFilename	string	No
splitUnify	boolean	No	For pages: one file holding every range instead of one per range.

Responses

Status	Meaning	Body
200	A PDF, or a ZIP of PDFs	File
400	The request is wrong	ErrorBody

POST /v1/pdf/stamp

Puts text, an image or a PDF over the content of each page.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	Two PDFs: the base, then the overlay laid over it page by page.
outputFilename	string	No

Responses

Status	Meaning	Body
200	The stamped PDF	File
400	The request is wrong	ErrorBody

POST /v1/pdf/watermark

Puts text, an image or a PDF under the content of each page.

Needs credentials, if any are configured.

Request

multipart/form-data

Field	Type	Required	Description
files	files	Yes	Two PDFs: the base, then the overlay laid over it page by page.
outputFilename	string	No

Responses

Status	Meaning	Body
200	The watermarked PDF	File
400	The request is wrong	ErrorBody