> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chromiumly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

> PageProperties, ConversionOptions, ImageProperties, PdfFormat, Split, and other shared types.

## PdfFormat

```typescript theme={null}
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)

| Property          | Type                                   | Default / notes                                                  |
| ----------------- | -------------------------------------- | ---------------------------------------------------------------- |
| singlePage        | boolean                                | false                                                            |
| size              | `{ width, height }` (number or string) | width/height in inches (number) or units: pt, px, in, mm, cm, pc |
| margins           | object (top, bottom, left, right)      | same units as size                                               |
| preferCssPageSize | boolean                                | false                                                            |
| printBackground   | boolean                                | false                                                            |
| omitBackground    | boolean                                | false                                                            |
| landscape         | boolean                                | false                                                            |
| scale             | number                                 | 1.0                                                              |
| nativePageRanges  | object with from, to (numbers)         | —                                                                |

## ImageProperties (screenshots)

| Property       | Type                          | Notes            |
| -------------- | ----------------------------- | ---------------- |
| format         | `'png'` / `'jpeg'` / `'webp'` | required         |
| quality        | number                        | 0–100, JPEG only |
| omitBackground | boolean                       | —                |
| width          | number                        | default 800      |
| height         | number                        | default 600      |
| clip           | boolean                       | default false    |

## Split

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

## Metadata

```typescript theme={null}
type Metadata = { [key: string]: boolean | number | string | string[] };
```

Use standard PDF/XMP keys (e.g. Author, Title, Keywords). See [ExifTool PDF/XMP](https://exiftool.org/TagNames/XMP.html#pdf).

## DownloadFrom

```typescript theme={null}
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

```typescript theme={null}
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.

## Cookie

```typescript theme={null}
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](/reference/converters) and [Chromium options](/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.

```typescript theme={null}
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()`.

```typescript theme={null}
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

```typescript theme={null}
type Bookmark = {
  title: string;
  page: number;
  children?: Bookmark[];
};
```

## Template types (hosted API)

The hosted `Templates` class exports these types:

```typescript theme={null}
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>`.