Set the bookmarks

Replaces the bookmarks, the outline viewers show beside the pages.

POST/forms/pdf/set-bookmarks

Form data

filesfile[]required

The PDFs.

archivesfile[]

ZIP files Gotenberg unpacks: each entry counts as a file uploaded under files.

downloadFromjson

URLs Gotenberg downloads first, as if you had uploaded the files. Each entry takes a url, and optionally extraHttpHeaders.

Options

bookmarkslistrequired

Items with a title, a pageNumber, and optional children items.

Response

The PDF, or a ZIP of the PDFs when you send several.

The route also takes the headers. An error answers a status and a message: see Errors.

curl \
  --request POST http://localhost:3000/forms/pdf/set-bookmarks \
  --form files=@report.pdf \
  --form 'bookmarks=[
    { "title": "Summary", "pageNumber": 1, "children": [ { "title": "Figures", "pageNumber": 2 } ] },
    { "title": "Appendix", "pageNumber": 3 }
  ]' \
  -o report.pdf

The list replaces the bookmarks the PDF had. children nests bookmarks under another, as deep as you need. /forms/pdf/bookmarks reads them in the same shape.

A request without bookmarks, or with an empty list, answers 400, and so does a bookmark without a title. A pageNumber outside 1 to the page count answers 400 too:

Invalid form data: form field 'stages' is invalid: stage 0: set-bookmarks: bookmarks[0].title is required
Stage 'set-bookmarks' failed on 'report.pdf': bookmarks[0].pageNumber 9 is past the last page 3

Build them from headings

Chromium builds bookmarks from the page's headings with nativeBookmarks. LibreOffice exports a document's headings as bookmarks without being asked: nativeBookmarks is on by default.

In a list of stages

The stage also runs in a list on /forms/pdf/pipe, and on the PDFs a Chromium or LibreOffice conversion makes, in its stages field:

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@report.pdf \
  --form 'stages=[
    { "op": "set-bookmarks", "bookmarks": [ { "title": "Summary", "pageNumber": 1, "children": [ { "title": "Figures", "pageNumber": 2 } ] }, { "title": "Appendix", "pageNumber": 3 } ] }
  ]' \
  -o report.pdf