Skip to main content

​
PdfFormat

enum PdfFormat {
  A_1a = "PDF/A-1a", // deprecated for LibreOffice from Gotenberg 7.6
  A_2b = "PDF/A-2b",
  A_3b = "PDF/A-3b",
}

​
PathLikeOrReadStream

string (file path), Buffer, or ReadStream (from fs).

​
PageProperties (converters)

PropertyTypeDefault / notes
singlePagebooleanfalse
size{ width, height } (number or string)width/height in inches (number) or units: pt, px, in, mm, cm, pc
marginsobject (top, bottom, left, right)same units as size
preferCssPageSizebooleanfalse
printBackgroundbooleanfalse
omitBackgroundbooleanfalse
landscapebooleanfalse
scalenumber1.0
nativePageRangesobject with from, to (numbers)—

​
ImageProperties (screenshots)

PropertyTypeNotes
format'png' / 'jpeg' / 'webp'required
qualitynumber0–100, JPEG only
omitBackgroundboolean—
widthnumberdefault 800
heightnumberdefault 600
clipbooleandefault false

​
Split

type Split = {
  mode: "pages" | "intervals";
  span: string; // e.g. "1-2", "1,3,5"
  unify?: boolean; // only for mode 'pages'
  flatten?: boolean;
};

​
Metadata

type Metadata = { [key: string]: boolean | number | string | string[] };
Use standard PDF/XMP keys (e.g. Author, Title, Keywords). See ExifTool PDF/XMP.

​
DownloadFrom

type DownloadFromEntry = {
  url: string;
  extraHttpHeaders?: Record<string, string>;
  embedded?: boolean;
  field?: "embedded" | "watermark" | "stamp" | "";
};

type DownloadFrom = DownloadFromEntry | DownloadFromEntry[];
Use downloadFrom when Gotenberg should fetch files from remote URLs that return a Content-Disposition filename.

​
WebhookOptions

type WebhookOptions = {
  webhookUrl: string;
  webhookErrorUrl: string;
  webhookMethod?: "POST" | "PUT" | "PATCH";
  webhookErrorMethod?: "POST" | "PUT" | "PATCH";
  webhookExtraHttpHeaders?: Record<string, string>;
  webhookEventsUrl?: string;
};
Use webhook to switch a request to async callback mode. 
type Cookie = {
  name: string;
  value: string;
  domain: string;
  path?: string;
  secure?: boolean;
  httpOnly?: boolean;
  sameSite?: "Strict" | "Lax" | "None";
};

​
EmulatedMediaType / EmulatedMediaFeature

  • EmulatedMediaType: 'screen' or 'print'
  • EmulatedMediaFeature: object with name and value strings (e.g. prefers-color-scheme, prefers-reduced-motion)
Conversion options include the shared Chromium options (header, footer, wait*, extraHttpHeaders, failOn*, skipNetworkIdleEvent, skipNetworkAlmostIdleEvent, cookies, downloadFrom, etc.) plus properties, pdfUA, metadata, split, userPassword, ownerPassword, embeds. See the source or Converters and Chromium options for the full list.

​
PdfEngineRotate

Used by converter convert(), LibreOffice.convert(), PDFEngines.merge(), and PDFEngines.split() as optional post-processing. Angles match Gotenberg: 90, 180, or 270 degrees. 
type PdfEngineRotate = {
  angle: 90 | 180 | 270;
  pages?: string; // e.g. "1-3", "5"; omit for all pages
};

​
PdfEngineWatermark / PdfEngineStamp

Used by converter convert(), LibreOffice.convert(), PDFEngines.merge(), PDFEngines.split(), and dedicated PDFEngines.watermark() / PDFEngines.stamp(). 
type PdfEngineWatermark = {
  source?: "text" | "image" | "pdf";
  expression?: string;
  pages?: string;
  options?: Record<string, unknown>;
  file?: PathLikeOrReadStream | Buffer;
};

type PdfEngineStamp = {
  source?: "text" | "image" | "pdf";
  expression?: string;
  pages?: string;
  options?: Record<string, unknown>;
  file?: PathLikeOrReadStream | Buffer;
};
For image/pdf sources, set expression to the uploaded filename and pass the asset in file.

​
Bookmark

type Bookmark = {
  title: string;
  page: number;
  children?: Bookmark[];
};

​
Template types (hosted API)

The hosted Templates class exports these types: 
type TemplateType =
  | "invoice_freelancer"
  | "invoice_saas"
  | "invoice_classic"
  | "invoice_minimal"
  | "invoice_modern";

type TemplateRequest<TType extends TemplateType> = {
  type: TType;
  data: TemplateDataByType[TType];
};
Templates.generate(request, { validate?: boolean }) uses TemplateRequest<TType> and returns Promise<Buffer>.