Bookmarks

Bookmarks, or the outline, are the clickable table of contents in a PDF viewer’s sidebar. Read them as JSON, or replace them.

Read

POST https://api.pdfdispatch.com/v1/pdf/bookmarks/read

Field	Type	Default	What it does
`files` required	file(s)	–	One or more PDFs. Each is handled on its own; several come back as a ZIP.

curl --fail-with-body \
  --header "Authorization: Bearer $PDD_KEY" \
  --form files=@handbook.pdf \
  https://api.pdfdispatch.com/v1/pdf/bookmarks/read

{
  "handbook.pdf": [
    { "title": "Welcome", "page": 1 },
    { "title": "Working here", "page": 3, "children": [
      { "title": "Hours", "page": 3 },
      { "title": "Holidays", "page": 5 }
    ] }
  ]
}

Write

POST https://api.pdfdispatch.com/v1/pdf/bookmarks/write

Field	Type	Default	What it does
`files` required	file(s)	–	The PDFs to change.
`bookmarks` required	JSON	–	A list of `{"title": "...", "page": 1, "children": [...]}`, which replaces the outline of every file; or an object of file name to list, to give each file its own.

curl --fail-with-body \
  --header "Authorization: Bearer $PDD_KEY" \
  --form files=@handbook.pdf \
  --form 'bookmarks=[{"title": "Welcome", "page": 1}, {"title": "Working here", "page": 3, "children": [{"title": "Holidays", "page": 5}]}]' \
  --output handbook.pdf \
  https://api.pdfdispatch.com/v1/pdf/bookmarks/write

Pages count from 1. When you merge, autoIndexBookmarks and titleBookmarks build the outline for you. For HTML, generateDocumentOutline=true makes bookmarks from the headings (Rendering options).