API Reference

PDFGate

Client for the PDFGate API.

Attributes:

Name	Type	Description
api_key	str	API key used for authentication.
domain	str	Base API domain derived from the API key.
request_builder	RequestBuilder	Builds HTTP requests for the API from parameter objects.
sync_client	PDFGateHTTPClientSync	Synchronous HTTP client that handles HTTP errors.
async_client	PDFGateHTTPClientAsync	Asynchronous HTTP client that handles HTTP errors.

Source code in src/pdfgate/pdfgate.py

class PDFGate:
    """Client for the PDFGate API.

    Attributes:
        api_key (str):
            API key used for authentication.
        domain (str):
            Base API domain derived from the API key.
        request_builder (RequestBuilder):
            Builds HTTP requests for the API from parameter objects.
        sync_client (PDFGateHTTPClientSync):
            Synchronous HTTP client that handles HTTP errors.
        async_client (PDFGateHTTPClientAsync):
            Asynchronous HTTP client that handles HTTP errors.
    """

    def __init__(self, api_key: str):
        """Initialize a PDFGate client.

        Args:
            api_key: The API key to use. Must start with 'live_' or 'test_'.

        Raises:
            PDFGateError: If the API key is invalid.
        """
        self.domain = get_domain_from_api_key(api_key)
        self.api_key = api_key
        self.request_builder = RequestBuilder(api_key=api_key)
        self.sync_client = PDFGateHTTPClientSync(api_key=api_key)
        self.async_client = PDFGateHTTPClientAsync(api_key=api_key)

    def get_document(self, params: GetDocumentParams) -> PDFGateDocument:
        """Retrieve a stored document’s metadata (and optionally a fresh pre-signed download URL).

        Returns:
            A `PDFGateDocument` parsed from the JSON response.

        Raises:
            PDFGateError: If the HTTP request fails (including non-2xx responses) or if
                there is a network/connection error. The error includes status code
                and message when available.
        """
        request = self.request_builder.build_get_document(params)
        response = self.sync_client.try_make_request(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    async def get_document_async(self, params: GetDocumentParams) -> PDFGateDocument:
        """Retrieve a stored document’s metadata (and optionally a fresh pre-signed download URL).

        Returns:
            A `PDFGateDocument` parsed from the JSON response.

        Raises:
            PDFGateError: If the HTTP request fails (including non-2xx responses) or if
                there is a network/connection error. The error includes status code
                and message when available.
        """
        request = self.request_builder.build_get_document(params)
        response = await self.async_client.try_make_request_async(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    def get_file(self, params: GetFileParams) -> bytes:
        """Download a raw PDF file by its document ID.

        Important: Accessing stored generated files requires enabling
        “Save files” in the PDFGate Dashboard settings (disabled by default).

        Returns:
            The raw bytes of the file.
        """
        request = self.request_builder.build_get_file(params.document_id)
        response = self.sync_client.try_make_request(request=request)

        return response.content

    async def get_file_async(self, params: GetFileParams) -> bytes:
        """Download a raw PDF file by its document ID.

        Important: Accessing stored generated files requires enabling
        “Save files” in the PDFGate Dashboard settings (disabled by default).

        Returns:
            The raw bytes of the file.
        """
        request = self.request_builder.build_get_file(params.document_id)
        response = await self.async_client.try_make_request_async(request=request)

        return response.content

    def generate_pdf(self, params: GeneratePDFParams) -> PDFGateDocument:
        """Generate a PDF from a URL or raw HTML.

        Returns:
            A `PDFGateDocument` parsed from the JSON response.
        """
        if not params.html and not params.url:
            raise ParamsValidationError(
                "Either the 'html' or 'url' parameters must be provided to generate a PDF."
            )

        request = self.request_builder.build_generate_pdf(params)
        response = self.sync_client.try_make_request(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    async def generate_pdf_async(self, params: GeneratePDFParams) -> PDFGateDocument:
        """Generate a PDF from a URL or raw HTML.

        Returns:
            A `PDFGateDocument` parsed from the JSON response.
        """
        if not params.html and not params.url:
            raise ParamsValidationError(
                "Either the 'html' or 'url' parameters must be provided to generate a PDF."
            )

        request = self.request_builder.build_generate_pdf(params)
        response = await self.async_client.try_make_request_async(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    def flatten_pdf(self, params: FlattenPDFParams) -> PDFGateDocument:
        """Flatten an interactive PDF into a static, non-editable PDF.

        Args:
            params: A `FlattenPDFParams` instance.

        Returns:
            A `PDFGateDocument` instance.
        """
        request = self.request_builder.build_flatten_pdf(params)
        response = self.sync_client.try_make_request(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    async def flatten_pdf_async(self, params: FlattenPDFParams) -> PDFGateDocument:
        """Flatten an interactive PDF into a static, non-editable PDF.

        Args:
            params: A `FlattenPDFParams` instance.

        Returns:
            A `PDFGateDocument` instance.
        """
        request = self.request_builder.build_flatten_pdf(params)
        response = await self.async_client.try_make_request_async(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    def extract_pdf_form_data(self, params: ExtractPDFFormDataParams) -> Any:
        """Extract form field data from a fillable PDF and return it as JSON.

        Args:
            params: A `ExtractPDFFormDataParams` instance.

        Returns:
            JSON object mapping form field names to their values.
        """
        request = self.request_builder.build_extract_pdf_form_data(params)
        response = self.sync_client.try_make_request(request)
        result = ResponseBuilder.build_json_response(response)

        return result

    async def extract_pdf_form_data_async(
        self, params: ExtractPDFFormDataParams
    ) -> Any:
        """Extract form field data from a fillable PDF and return it as JSON.

        Args:
            params: A `ExtractPDFFormDataParams` instance.

        Returns:
            JSON object mapping form field names to their values.
        """
        request = self.request_builder.build_extract_pdf_form_data(params)
        response = await self.async_client.try_make_request_async(request)
        result = ResponseBuilder.build_json_response(response)

        return result

    def protect_pdf(self, params: ProtectPDFParams) -> PDFGateDocument:
        """Protect a PDF using encryption + optional permission restrictions.

        Security options highlights:
            - `algorithm`: `"AES256"` (default) or `"AES128"`.
            - `user_password`: password required to open the PDF (optional).
            - `owner_password`: full control password; required in some cases (e.g., AES256 with `user_password`).
            - Restrictions: `disable_print`, `disable_copy`, `disable_editing`.
            - `encrypt_metadata`: whether PDF metadata is encrypted (default `False`).

        Args:
            params: A `ProtectPDFParams` instance.

        Returns:
            A `PDFGateDocument` instance.
        """
        request = self.request_builder.build_protect_pdf(params)
        response = self.sync_client.try_make_request(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    async def protect_pdf_async(self, params: ProtectPDFParams) -> PDFGateDocument:
        """Protect a PDF using encryption + optional permission restrictions.

        Security options highlights:
            - `algorithm`: `"AES256"` (default) or `"AES128"`.
            - `user_password`: password required to open the PDF (optional).
            - `owner_password`: full control password; required in some cases (e.g., AES256 with `user_password`).
            - Restrictions: `disable_print`, `disable_copy`, `disable_editing`.
            - `encrypt_metadata`: whether PDF metadata is encrypted (default `False`).

        Args:
            params: A `ProtectPDFParams` instance.

        Returns:
            A `PDFGateDocument` instance.
        """
        request = self.request_builder.build_protect_pdf(params)
        response = await self.async_client.try_make_request_async(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    def compress_pdf(self, params: CompressPDFParams) -> PDFGateDocument:
        """Compress a PDF document to reduce its size without changing its visual content.

        Args:
            params: A `CompressPDFParams` instance.

        Returns:
            A `PDFGateDocument` instance.
        """
        request = self.request_builder.build_compress_pdf(params)
        response = self.sync_client.try_make_request(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    async def compress_pdf_async(self, params: CompressPDFParams) -> PDFGateDocument:
        """Compress a PDF document to reduce its size without changing its visual content.

        Args:
            params: A `CompressPDFParams` instance.

        Returns:
            A `PDFGateDocument` instance.
        """
        request = self.request_builder.build_compress_pdf(params)
        response = await self.async_client.try_make_request_async(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    def watermark_pdf(self, params: WatermarkPDFParams) -> PDFGateDocument:
        """Apply a text or image watermark to a PDF.

        Watermark configuration highlights:
            - `type` is required: `"text"` or `"image"`.
            - For text watermarks: `text` required when `type="text"`.
            - For image watermarks: upload `watermark` image file (`.png`, `.jpg`, `.jpeg`).
            - Optional: `font` (standard PDF fonts), `fontFile`
            (`.ttf`/`.otf` overrides `font`), `fontSize`, `fontColor`,
            `opacity` (0..1), `xPosition`, `yPosition`, `imageWidth`, `imageHeight`,
            `rotate` (0..360).

        Args:
            params: A `WatermarkPDFParams` instance.

        Returns:
            A `PDFGateDocument` instance.
        """
        request = self.request_builder.build_watermark_pdf(params)
        response = self.sync_client.try_make_request(request)
        result = ResponseBuilder.build_document_response(response)

        return result

    async def watermark_pdf_async(self, params: WatermarkPDFParams) -> PDFGateDocument:
        """Apply a text or image watermark to a PDF.

        Watermark configuration highlights:
            - `type` is required: `"text"` or `"image"`.
            - For text watermarks: `text` required when `type="text"`.
            - For image watermarks: upload `watermark` image file (`.png`, `.jpg`, `.jpeg`).
            - Optional: `font` (standard PDF fonts), `fontFile`
            (`.ttf`/`.otf` overrides `font`), `fontSize`, `fontColor`,
            `opacity` (0..1), `xPosition`, `yPosition`, `imageWidth`, `imageHeight`,
            `rotate` (0..360).

        Args:
            params: A `WatermarkPDFParams` instance.

        Returns:
            A `PDFGateDocument` instance.
        """
        request = self.request_builder.build_watermark_pdf(params)
        response = await self.async_client.try_make_request_async(request)
        result = ResponseBuilder.build_document_response(response)

        return result

__init__(api_key)

Initialize a PDFGate client.

Parameters:

Name	Type	Description	Default
api_key	str	The API key to use. Must start with 'live_' or 'test_'.	required

Raises:

Type	Description
PDFGateError	If the API key is invalid.

Source code in src/pdfgate/pdfgate.py

def __init__(self, api_key: str):
    """Initialize a PDFGate client.

    Args:
        api_key: The API key to use. Must start with 'live_' or 'test_'.

    Raises:
        PDFGateError: If the API key is invalid.
    """
    self.domain = get_domain_from_api_key(api_key)
    self.api_key = api_key
    self.request_builder = RequestBuilder(api_key=api_key)
    self.sync_client = PDFGateHTTPClientSync(api_key=api_key)
    self.async_client = PDFGateHTTPClientAsync(api_key=api_key)

compress_pdf(params)

Compress a PDF document to reduce its size without changing its visual content.

Parameters:

Name	Type	Description	Default
params	CompressPDFParams	A CompressPDFParams instance.	required

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument instance.

Source code in src/pdfgate/pdfgate.py

def compress_pdf(self, params: CompressPDFParams) -> PDFGateDocument:
    """Compress a PDF document to reduce its size without changing its visual content.

    Args:
        params: A `CompressPDFParams` instance.

    Returns:
        A `PDFGateDocument` instance.
    """
    request = self.request_builder.build_compress_pdf(params)
    response = self.sync_client.try_make_request(request)
    result = ResponseBuilder.build_document_response(response)

    return result

compress_pdf_async(params) async

Compress a PDF document to reduce its size without changing its visual content.

Parameters:

Name	Type	Description	Default
params	CompressPDFParams	A CompressPDFParams instance.	required

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument instance.

Source code in src/pdfgate/pdfgate.py

async def compress_pdf_async(self, params: CompressPDFParams) -> PDFGateDocument:
    """Compress a PDF document to reduce its size without changing its visual content.

    Args:
        params: A `CompressPDFParams` instance.

    Returns:
        A `PDFGateDocument` instance.
    """
    request = self.request_builder.build_compress_pdf(params)
    response = await self.async_client.try_make_request_async(request)
    result = ResponseBuilder.build_document_response(response)

    return result

extract_pdf_form_data(params)

Extract form field data from a fillable PDF and return it as JSON.

Parameters:

Name	Type	Description	Default
params	ExtractPDFFormDataParams	A ExtractPDFFormDataParams instance.	required

Returns:

Type	Description
Any	JSON object mapping form field names to their values.

Source code in src/pdfgate/pdfgate.py

def extract_pdf_form_data(self, params: ExtractPDFFormDataParams) -> Any:
    """Extract form field data from a fillable PDF and return it as JSON.

    Args:
        params: A `ExtractPDFFormDataParams` instance.

    Returns:
        JSON object mapping form field names to their values.
    """
    request = self.request_builder.build_extract_pdf_form_data(params)
    response = self.sync_client.try_make_request(request)
    result = ResponseBuilder.build_json_response(response)

    return result

extract_pdf_form_data_async(params) async

Extract form field data from a fillable PDF and return it as JSON.

Parameters:

Name	Type	Description	Default
params	ExtractPDFFormDataParams	A ExtractPDFFormDataParams instance.	required

Returns:

Type	Description
Any	JSON object mapping form field names to their values.

Source code in src/pdfgate/pdfgate.py

async def extract_pdf_form_data_async(
    self, params: ExtractPDFFormDataParams
) -> Any:
    """Extract form field data from a fillable PDF and return it as JSON.

    Args:
        params: A `ExtractPDFFormDataParams` instance.

    Returns:
        JSON object mapping form field names to their values.
    """
    request = self.request_builder.build_extract_pdf_form_data(params)
    response = await self.async_client.try_make_request_async(request)
    result = ResponseBuilder.build_json_response(response)

    return result

flatten_pdf(params)

Flatten an interactive PDF into a static, non-editable PDF.

Parameters:

Name	Type	Description	Default
params	FlattenPDFParams	A FlattenPDFParams instance.	required

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument instance.

Source code in src/pdfgate/pdfgate.py

def flatten_pdf(self, params: FlattenPDFParams) -> PDFGateDocument:
    """Flatten an interactive PDF into a static, non-editable PDF.

    Args:
        params: A `FlattenPDFParams` instance.

    Returns:
        A `PDFGateDocument` instance.
    """
    request = self.request_builder.build_flatten_pdf(params)
    response = self.sync_client.try_make_request(request)
    result = ResponseBuilder.build_document_response(response)

    return result

flatten_pdf_async(params) async

Flatten an interactive PDF into a static, non-editable PDF.

Parameters:

Name	Type	Description	Default
params	FlattenPDFParams	A FlattenPDFParams instance.	required

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument instance.

Source code in src/pdfgate/pdfgate.py

async def flatten_pdf_async(self, params: FlattenPDFParams) -> PDFGateDocument:
    """Flatten an interactive PDF into a static, non-editable PDF.

    Args:
        params: A `FlattenPDFParams` instance.

    Returns:
        A `PDFGateDocument` instance.
    """
    request = self.request_builder.build_flatten_pdf(params)
    response = await self.async_client.try_make_request_async(request)
    result = ResponseBuilder.build_document_response(response)

    return result

generate_pdf(params)

Generate a PDF from a URL or raw HTML.

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument parsed from the JSON response.

Source code in src/pdfgate/pdfgate.py

def generate_pdf(self, params: GeneratePDFParams) -> PDFGateDocument:
    """Generate a PDF from a URL or raw HTML.

    Returns:
        A `PDFGateDocument` parsed from the JSON response.
    """
    if not params.html and not params.url:
        raise ParamsValidationError(
            "Either the 'html' or 'url' parameters must be provided to generate a PDF."
        )

    request = self.request_builder.build_generate_pdf(params)
    response = self.sync_client.try_make_request(request)
    result = ResponseBuilder.build_document_response(response)

    return result

generate_pdf_async(params) async

Generate a PDF from a URL or raw HTML.

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument parsed from the JSON response.

Source code in src/pdfgate/pdfgate.py

async def generate_pdf_async(self, params: GeneratePDFParams) -> PDFGateDocument:
    """Generate a PDF from a URL or raw HTML.

    Returns:
        A `PDFGateDocument` parsed from the JSON response.
    """
    if not params.html and not params.url:
        raise ParamsValidationError(
            "Either the 'html' or 'url' parameters must be provided to generate a PDF."
        )

    request = self.request_builder.build_generate_pdf(params)
    response = await self.async_client.try_make_request_async(request)
    result = ResponseBuilder.build_document_response(response)

    return result

get_document(params)

Retrieve a stored document’s metadata (and optionally a fresh pre-signed download URL).

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument parsed from the JSON response.

Raises:

Type	Description
PDFGateError	If the HTTP request fails (including non-2xx responses) or if there is a network/connection error. The error includes status code and message when available.

Source code in src/pdfgate/pdfgate.py

def get_document(self, params: GetDocumentParams) -> PDFGateDocument:
    """Retrieve a stored document’s metadata (and optionally a fresh pre-signed download URL).

    Returns:
        A `PDFGateDocument` parsed from the JSON response.

    Raises:
        PDFGateError: If the HTTP request fails (including non-2xx responses) or if
            there is a network/connection error. The error includes status code
            and message when available.
    """
    request = self.request_builder.build_get_document(params)
    response = self.sync_client.try_make_request(request)
    result = ResponseBuilder.build_document_response(response)

    return result

get_document_async(params) async

Retrieve a stored document’s metadata (and optionally a fresh pre-signed download URL).

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument parsed from the JSON response.

Raises:

Type	Description
PDFGateError	If the HTTP request fails (including non-2xx responses) or if there is a network/connection error. The error includes status code and message when available.

Source code in src/pdfgate/pdfgate.py

async def get_document_async(self, params: GetDocumentParams) -> PDFGateDocument:
    """Retrieve a stored document’s metadata (and optionally a fresh pre-signed download URL).

    Returns:
        A `PDFGateDocument` parsed from the JSON response.

    Raises:
        PDFGateError: If the HTTP request fails (including non-2xx responses) or if
            there is a network/connection error. The error includes status code
            and message when available.
    """
    request = self.request_builder.build_get_document(params)
    response = await self.async_client.try_make_request_async(request)
    result = ResponseBuilder.build_document_response(response)

    return result

get_file(params)

Download a raw PDF file by its document ID.

Important: Accessing stored generated files requires enabling “Save files” in the PDFGate Dashboard settings (disabled by default).

Returns:

Type	Description
bytes	The raw bytes of the file.

Source code in src/pdfgate/pdfgate.py

def get_file(self, params: GetFileParams) -> bytes:
    """Download a raw PDF file by its document ID.

    Important: Accessing stored generated files requires enabling
    “Save files” in the PDFGate Dashboard settings (disabled by default).

    Returns:
        The raw bytes of the file.
    """
    request = self.request_builder.build_get_file(params.document_id)
    response = self.sync_client.try_make_request(request=request)

    return response.content

get_file_async(params) async

Download a raw PDF file by its document ID.

Important: Accessing stored generated files requires enabling “Save files” in the PDFGate Dashboard settings (disabled by default).

Returns:

Type	Description
bytes	The raw bytes of the file.

Source code in src/pdfgate/pdfgate.py

async def get_file_async(self, params: GetFileParams) -> bytes:
    """Download a raw PDF file by its document ID.

    Important: Accessing stored generated files requires enabling
    “Save files” in the PDFGate Dashboard settings (disabled by default).

    Returns:
        The raw bytes of the file.
    """
    request = self.request_builder.build_get_file(params.document_id)
    response = await self.async_client.try_make_request_async(request=request)

    return response.content

protect_pdf(params)

Protect a PDF using encryption + optional permission restrictions.

Security options highlights

• algorithm: "AES256" (default) or "AES128".
• user_password: password required to open the PDF (optional).
• owner_password: full control password; required in some cases (e.g., AES256 with user_password).
• Restrictions: disable_print, disable_copy, disable_editing.
• encrypt_metadata: whether PDF metadata is encrypted (default False).

Parameters:

Name	Type	Description	Default
params	ProtectPDFParams	A ProtectPDFParams instance.	required

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument instance.

Source code in src/pdfgate/pdfgate.py

def protect_pdf(self, params: ProtectPDFParams) -> PDFGateDocument:
    """Protect a PDF using encryption + optional permission restrictions.

    Security options highlights:
        - `algorithm`: `"AES256"` (default) or `"AES128"`.
        - `user_password`: password required to open the PDF (optional).
        - `owner_password`: full control password; required in some cases (e.g., AES256 with `user_password`).
        - Restrictions: `disable_print`, `disable_copy`, `disable_editing`.
        - `encrypt_metadata`: whether PDF metadata is encrypted (default `False`).

    Args:
        params: A `ProtectPDFParams` instance.

    Returns:
        A `PDFGateDocument` instance.
    """
    request = self.request_builder.build_protect_pdf(params)
    response = self.sync_client.try_make_request(request)
    result = ResponseBuilder.build_document_response(response)

    return result

protect_pdf_async(params) async

Protect a PDF using encryption + optional permission restrictions.

Security options highlights

• algorithm: "AES256" (default) or "AES128".
• user_password: password required to open the PDF (optional).
• owner_password: full control password; required in some cases (e.g., AES256 with user_password).
• Restrictions: disable_print, disable_copy, disable_editing.
• encrypt_metadata: whether PDF metadata is encrypted (default False).

Parameters:

Name	Type	Description	Default
params	ProtectPDFParams	A ProtectPDFParams instance.	required

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument instance.

Source code in src/pdfgate/pdfgate.py

async def protect_pdf_async(self, params: ProtectPDFParams) -> PDFGateDocument:
    """Protect a PDF using encryption + optional permission restrictions.

    Security options highlights:
        - `algorithm`: `"AES256"` (default) or `"AES128"`.
        - `user_password`: password required to open the PDF (optional).
        - `owner_password`: full control password; required in some cases (e.g., AES256 with `user_password`).
        - Restrictions: `disable_print`, `disable_copy`, `disable_editing`.
        - `encrypt_metadata`: whether PDF metadata is encrypted (default `False`).

    Args:
        params: A `ProtectPDFParams` instance.

    Returns:
        A `PDFGateDocument` instance.
    """
    request = self.request_builder.build_protect_pdf(params)
    response = await self.async_client.try_make_request_async(request)
    result = ResponseBuilder.build_document_response(response)

    return result

watermark_pdf(params)

Apply a text or image watermark to a PDF.

Watermark configuration highlights

• type is required: "text" or "image".
• For text watermarks: text required when type="text".
• For image watermarks: upload watermark image file (.png, .jpg, .jpeg).
• Optional: font (standard PDF fonts), fontFile (.ttf/.otf overrides font), fontSize, fontColor, opacity (0..1), xPosition, yPosition, imageWidth, imageHeight, rotate (0..360).

Parameters:

Name	Type	Description	Default
params	WatermarkPDFParams	A WatermarkPDFParams instance.	required

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument instance.

Source code in src/pdfgate/pdfgate.py

def watermark_pdf(self, params: WatermarkPDFParams) -> PDFGateDocument:
    """Apply a text or image watermark to a PDF.

    Watermark configuration highlights:
        - `type` is required: `"text"` or `"image"`.
        - For text watermarks: `text` required when `type="text"`.
        - For image watermarks: upload `watermark` image file (`.png`, `.jpg`, `.jpeg`).
        - Optional: `font` (standard PDF fonts), `fontFile`
        (`.ttf`/`.otf` overrides `font`), `fontSize`, `fontColor`,
        `opacity` (0..1), `xPosition`, `yPosition`, `imageWidth`, `imageHeight`,
        `rotate` (0..360).

    Args:
        params: A `WatermarkPDFParams` instance.

    Returns:
        A `PDFGateDocument` instance.
    """
    request = self.request_builder.build_watermark_pdf(params)
    response = self.sync_client.try_make_request(request)
    result = ResponseBuilder.build_document_response(response)

    return result

watermark_pdf_async(params) async

Apply a text or image watermark to a PDF.

Watermark configuration highlights

• type is required: "text" or "image".
• For text watermarks: text required when type="text".
• For image watermarks: upload watermark image file (.png, .jpg, .jpeg).
• Optional: font (standard PDF fonts), fontFile (.ttf/.otf overrides font), fontSize, fontColor, opacity (0..1), xPosition, yPosition, imageWidth, imageHeight, rotate (0..360).

Parameters:

Name	Type	Description	Default
params	WatermarkPDFParams	A WatermarkPDFParams instance.	required

Returns:

Type	Description
PDFGateDocument	A PDFGateDocument instance.

Source code in src/pdfgate/pdfgate.py

async def watermark_pdf_async(self, params: WatermarkPDFParams) -> PDFGateDocument:
    """Apply a text or image watermark to a PDF.

    Watermark configuration highlights:
        - `type` is required: `"text"` or `"image"`.
        - For text watermarks: `text` required when `type="text"`.
        - For image watermarks: upload `watermark` image file (`.png`, `.jpg`, `.jpeg`).
        - Optional: `font` (standard PDF fonts), `fontFile`
        (`.ttf`/`.otf` overrides `font`), `fontSize`, `fontColor`,
        `opacity` (0..1), `xPosition`, `yPosition`, `imageWidth`, `imageHeight`,
        `rotate` (0..360).

    Args:
        params: A `WatermarkPDFParams` instance.

    Returns:
        A `PDFGateDocument` instance.
    """
    request = self.request_builder.build_watermark_pdf(params)
    response = await self.async_client.try_make_request_async(request)
    result = ResponseBuilder.build_document_response(response)

    return result

Parameter types and enums used by PDFGate API calls.

ClickSelectorChain dataclass

Sequence of selectors to click in order.

Source code in src/pdfgate/params.py

@dataclass
class ClickSelectorChain:
    """Sequence of selectors to click in order."""

    selectors: list[str]

ClickSelectorChainSetup dataclass

Configuration for click selector chains.

Source code in src/pdfgate/params.py

@dataclass
class ClickSelectorChainSetup:
    """Configuration for click selector chains."""

    ignore_failing_chains: Optional[bool] = None
    chains: Optional[list["ClickSelectorChain"]] = None

CompressPDFParams dataclass

Bases: PDFGateParams

Parameters for compressing a PDF by document ID.

Source code in src/pdfgate/params.py

@dataclass
class CompressPDFParams(PDFGateParams):
    """Parameters for compressing a PDF by document ID."""

    document_id: Optional[str] = None
    linearize: Optional[bool] = None
    pre_signed_url_expires_in: Optional[int] = None
    metadata: Optional[Any] = None

EmulateMediaType

Bases: Enum

Media types for CSS emulation during rendering.

Source code in src/pdfgate/params.py

class EmulateMediaType(Enum):
    """Media types for CSS emulation during rendering."""

    SCREEN = "screen"
    PRINT = "print"

EncryptionAlgorithm

Bases: Enum

Supported encryption algorithms.

Source code in src/pdfgate/params.py

class EncryptionAlgorithm(Enum):
    """Supported encryption algorithms."""

    AES_256 = "AES256"
    AES_128 = "AES128"

ExtractPDFFormDataParams dataclass

Bases: PDFGateParams

Parameters for extracting form data by document ID.

Source code in src/pdfgate/params.py

@dataclass
class ExtractPDFFormDataParams(PDFGateParams):
    """Parameters for extracting form data by document ID."""

    document_id: str

FileOrientation

Bases: Enum

Orientation options for generated PDFs.

Source code in src/pdfgate/params.py

class FileOrientation(Enum):
    """Orientation options for generated PDFs."""

    PORTRAIT = "portrait"
    LANDSCAPE = "landscape"

FileParam

Bases: NamedTuple

Binary file payload for multipart uploads.

Source code in src/pdfgate/params.py

class FileParam(NamedTuple):
    """Binary file payload for multipart uploads."""

    name: str
    data: bytes
    type: Optional[str] = None

FlattenPDFParams dataclass

Bases: PDFGateParams

Parameters for flattening a PDF by document ID.

Source code in src/pdfgate/params.py

@dataclass
class FlattenPDFParams(PDFGateParams):
    """Parameters for flattening a PDF by document ID."""

    document_id: Optional[str] = None
    pre_signed_url_expires_in: Optional[int] = None
    metadata: Optional[Any] = None

GeneratePDFAuthentication dataclass

"Authentication credentials for accessing protected web content.

Source code in src/pdfgate/params.py

@dataclass
class GeneratePDFAuthentication:
    """ "Authentication credentials for accessing protected web content."""

    username: str
    password: str

GeneratePDFParams dataclass

Bases: PDFGateParams

Parameters for generating a PDF from HTML or a URL.

Source code in src/pdfgate/params.py

@dataclass
class GeneratePDFParams(PDFGateParams):
    """Parameters for generating a PDF from HTML or a URL."""

    html: Optional[str] = None
    url: Optional[str] = None
    pre_signed_url_expires_in: Optional[int] = None
    page_size_type: Optional[PageSizeType] = None
    width: Optional[int] = None
    height: Optional[int] = None
    orientation: Optional[FileOrientation] = None
    header: Optional[str] = None
    footer: Optional[str] = None
    margin: Optional[PdfPageMargin] = None
    timeout: Optional[int] = None
    javascript: Optional[str] = None
    css: Optional[str] = None
    emulate_media_type: Optional[EmulateMediaType] = None
    http_headers: Optional[dict[str, str]] = None
    metadata: Optional[Any] = None
    wait_for_selector: Optional[str] = None
    click_selector: Optional[str] = None
    click_selector_chain_setup: Optional[ClickSelectorChainSetup] = None
    wait_for_network_idle: Optional[bool] = None
    enable_form_fields: Optional[bool] = None
    delay: Optional[int] = None
    load_images: Optional[bool] = None
    scale: Optional[float] = None
    page_ranges: Optional[str] = None
    print_background: Optional[bool] = None
    user_agent: Optional[str] = None
    authentication: Optional[GeneratePDFAuthentication] = None
    viewport: Optional[Viewport] = None

GetDocumentParams dataclass

Bases: PDFGateParams

Parameters for fetching a document's metadata.

Source code in src/pdfgate/params.py

@dataclass
class GetDocumentParams(PDFGateParams):
    """Parameters for fetching a document's metadata."""

    document_id: str
    pre_signed_url_expires_in: Optional[int] = None

GetFileParams dataclass

Bases: PDFGateParams

Parameters for downloading a document's file content.

Source code in src/pdfgate/params.py

@dataclass
class GetFileParams(PDFGateParams):
    """Parameters for downloading a document's file content."""

    document_id: str

PDFGateParams dataclass

Marker base class for all parameter dataclasses.

Source code in src/pdfgate/params.py

@dataclass
class PDFGateParams:
    """Marker base class for all parameter dataclasses."""

    pass

PageSizeType

Bases: Enum

Supported page sizes for generated PDFs.

Source code in src/pdfgate/params.py

class PageSizeType(Enum):
    """Supported page sizes for generated PDFs."""

    A0 = "a0"
    A1 = "a1"
    A2 = "a2"
    A3 = "a3"
    A4 = "a4"
    A5 = "a5"
    A6 = "a6"
    LEDGER = "ledger"
    TABLOID = "tabloid"
    LEGAL = "legal"
    LETTER = "letter"

PdfPageMargin dataclass

Margins to apply to a PDF page.

Source code in src/pdfgate/params.py

@dataclass
class PdfPageMargin:
    """Margins to apply to a PDF page."""

    top: Optional[str] = None
    bottom: Optional[str] = None
    left: Optional[str] = None
    right: Optional[str] = None

PdfStandardFont

Bases: Enum

Standard built-in fonts supported by the renderer.

Source code in src/pdfgate/params.py

class PdfStandardFont(Enum):
    """Standard built-in fonts supported by the renderer."""

    TIMES_ROMAN = "times-roman"
    TIMES_BOLD = "times-bold"
    TIMES_ITALIC = "times-italic"
    TIMES_BOLD_ITALIC = "times-bolditalic"
    HELVETICA = "helvetica"
    HELVETICA_BOLD = "helvetica-bold"
    HELVETICA_OBLIQUE = "helvetica-oblique"
    HELVETICA_BOLD_OBLIQUE = "helvetica-boldoblique"
    COURIER = "courier"
    COURIER_BOLD = "courier-bold"
    COURIER_OBLIQUE = "courier-oblique"
    COURIER_BOLD_OBLIQUE = "courier-boldoblique"

ProtectPDFParams dataclass

Bases: PDFGateParams

Parameters for protecting a PDF by document ID.

Source code in src/pdfgate/params.py

@dataclass
class ProtectPDFParams(PDFGateParams):
    """Parameters for protecting a PDF by document ID."""

    document_id: Optional[str] = None
    algorithm: Optional[EncryptionAlgorithm] = None
    user_password: Optional[str] = None
    owner_password: Optional[str] = None
    disable_print: Optional[bool] = None
    disable_copy: Optional[bool] = None
    disable_editing: Optional[bool] = None
    encrypt_metadata: Optional[bool] = None
    pre_signed_url_expires_in: Optional[int] = None
    metadata: Optional[Any] = None

Viewport dataclass

Viewport dimensions for rendering.

Source code in src/pdfgate/params.py

@dataclass
class Viewport:
    """Viewport dimensions for rendering."""

    width: int
    height: int

WatermarkPDFParams dataclass

Bases: PDFGateParams

Parameters for watermarking a PDF by document ID.

Source code in src/pdfgate/params.py

@dataclass
class WatermarkPDFParams(PDFGateParams):
    """Parameters for watermarking a PDF by document ID."""

    type: WatermarkType
    document_id: Optional[str] = None
    text: Optional[str] = None
    watermark: Optional[FileParam] = None
    font: Optional[PdfStandardFont] = None
    font_size: Optional[int] = None
    font_color: Optional[str] = None
    opacity: Optional[float] = None
    x_position: Optional[int] = None
    y_position: Optional[int] = None
    image_width: Optional[int] = None
    image_height: Optional[int] = None
    rotate: Optional[float] = None
    pre_signed_url_expires_in: Optional[int] = None
    metadata: Optional[Any] = None

Response models for PDFGate API results.

DocumentType

Bases: Enum

Document types reported by the PDFGate API.

Source code in src/pdfgate/responses.py

class DocumentType(Enum):
    """Document types reported by the PDFGate API."""

    FROM_HTML = "from_html"
    FLATTENED = "flattened"
    WATERMARKED = "watermarked"
    ENCRYPTED = "encrypted"
    COMPRESSED = "compressed"
    SIGNED = "signed"

PDFGateDocument

Bases: TypedDict

Typed dictionary representing a PDFGate document response.

Source code in src/pdfgate/responses.py

class PDFGateDocument(TypedDict, total=False):
    """Typed dictionary representing a PDFGate document response."""

    id: str
    status: DocumentStatus
    created_at: datetime
    expires_at: datetime
    type: Optional[DocumentType]
    file_url: Optional[str]
    size: Optional[int]
    metadata: Optional[dict[str, Any]]
    derived_from: Optional[str]