▣ FILE MANIPULATION

Apply Watermark and Footers on PDF API

Hosted on ApyHub

What it does

PDF Header Footer Stamping adds a header and footer to a PDF, either from a file URL or an uploaded PDF, and returns the stamped document as a binary file or a signed URL.

Send a source PDF as a URL or a binary upload, then provide header and footer content as text or PNG images. For text, you can set shared font size and opacity, or control header and footer settings separately with alignment, font size, and opacity. For image-based stamping, you can set image size for each slot. The API also supports alias fields like header_text and footer_text, and when both text and image are provided for the same slot, text takes priority.

Use this when you need to add document labels, page context, or branded marks to reports, statements, generated PDFs, or archived files before sharing them internally or with customers. Choose the URL-based endpoints when your workflow stores files remotely, or the download endpoints when you want the stamped PDF streamed back immediately.

▣ ENDPOINT 01 / 04

POST

Stamp header/footer onto a PDF fetched from a URL, get a signed URL back

http://localhost:8080/apyhub/stamp-header-footer-on-pdf/url/url

QUICKSTARTGUIDE

Quickstart

Generate a stamped PDF link from a source PDF URL.

curl -X POST "http://localhost:8080/apyhub/stamp-header-footer-on-pdf/url/url" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://assets.apyhub.com/samples/sample.pdf",
    "header_text": "Confidential",
    "footer_text": "Page footer"
  }'

What you'll get back

Returns a JSON object with a url string field containing the generated PDF URL.

{
  "url": "https://example.com/output.pdf"
}

TRY ITLIVE · 200 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Fetches a PDF from a URL, stamps a header and/or footer onto it, and returns a signed URL to the processed PDF.

Request Body

Parameter	Type	Mandatory	Description
file_url	String	Yes	URL of the source PDF. Required.
footer	String	No	Additional footer content.
header	String	No	Additional header content.
font_size	Number	No	Font size for the stamp text. Minimum 8, maximum 24.
footer_text	String	No	Footer text content. One of `footer_text` or `footer_image_url` is required.
header_text	String	No	Header text content. One of `header_text` or `header_image_url` is required.
font_opacity	Number	No	Opacity for the stamp text. Minimum 0, maximum 1.
footer_opacity	Number	No	Opacity for the footer stamp. Default: 1. Minimum 0, maximum 1.
header_opacity	Number	No	Opacity for the header stamp. Default: 1. Minimum 0, maximum 1.
footer_alignment	ENUM	No	Footer alignment. Allowed values: `left`, `right`, `center`. Default: `center`.
footer_font_size	Number	No	Footer font size. Default: 12. Minimum 8, maximum 24.
footer_image_url	String	No	URL of a PNG image. Required if `footer_text` is not given.
header_alignment	ENUM	No	Header alignment. Allowed values: `left`, `right`, `center`. Default: `center`.
header_font_size	Number	No	Header font size. Default: 12. Minimum 8, maximum 24.
header_image_url	String	No	URL of a PNG image. Required if `header_text` is not given.
footer_image_size	Number	No	Footer image size. Default: 0.1. Minimum 0.1, maximum 1.
header_image_size	Number	No	Header image size. Default: 0.1. Minimum 0.1, maximum 1.

Response

Returns a JSON object with a url string field containing the signed URL of the processed PDF.

Parameter	Type	Mandatory	Description
url	String	No	Signed URL to the stamped PDF.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

DEFAULT test-sample

Body

Name

Type

Description

bodyREQUIRED

object

header_text/header_image_url (one required) and footer_text/footer_image_url (one required).

▣ ENDPOINT 02 / 04

POST

Stamp header/footer onto an uploaded PDF, stream result back

http://localhost:8080/apyhub/stamp-header-footer-on-pdf/file/download

QUICKSTARTGUIDE

Quickstart

Upload a PDF plus header and footer text to generate the stamped file.

curl -X POST "http://localhost:8080/apyhub/stamp-header-footer-on-pdf/file/download" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/input.pdf" \
  -F "header_text=Confidential" \
  -F "footer_text=Approved"

What you'll get back

Returns a binary file (string with format: binary) containing the stamped PDF.

%PDF-1.7
...

TRY ITLIVE · 200 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

body*

header_text/header_image (one required) and footer_text/footer_image (one required); if both text and image given for a slot, text wins.

file*

Source PDF file to stamp. Required.

Choose a file…

footer

header

font_size

Shared fallback for header_font_size/footer_font_size.

footer_text

Alias: footer. Required if footer_image not given. Wins over footer_image if both present.

header_text

Alias: header. Required if header_image not given. Wins over header_image if both present.

font_opacity

footer_image

PNG image. Required if footer_text not given.

Choose a file…

header_image

PNG image. Required if header_text not given.

Choose a file…

footer_opacity

header_opacity

Falls back to font_opacity when header_text set, else 1.

footer_alignment

footer_font_size

header_alignment

header_font_size

Falls back to font_size if unset.

footer_image_size

header_image_size

About this endpoint

What it does

Uploads a PDF file and returns the stamped PDF as a binary file download. You provide the source PDF plus header and footer content settings, where each slot accepts either text or an image.

Request Body

Parameter	Type	Mandatory	Description
file	String	Yes	Source PDF file to stamp. Required.
footer	String	No	Footer text content.
header	String	No	Header text content.
font_size	Number	No	Shared fallback for `header_font_size` / `footer_font_size`. Maximum 24, minimum 8.
footer_text	String	No	Alias for `footer`. Required if `footer_image` is not given. Wins over `footer_image` if both are present.
header_text	String	No	Alias for `header`. Required if `header_image` is not given. Wins over `header_image` if both are present.
font_opacity	Number	No	Shared opacity fallback. Maximum 1, minimum 0.
footer_image	String	No	PNG image. Required if `footer_text` is not given.
header_image	String	No	PNG image. Required if `header_text` is not given.
footer_opacity	Number	No	Footer opacity. Default 1, maximum 1, minimum 0.
header_opacity	Number	No	Header opacity. Default 1, maximum 1, minimum 0. Falls back to `font_opacity` when `header_text` is set, otherwise 1.
footer_alignment	ENUM	No	Footer alignment. Allowed values: `left`, `right`, `center`. Default `center`.
footer_font_size	Number	No	Footer font size. Default 12, maximum 24, minimum 8.
header_alignment	ENUM	No	Header alignment. Allowed values: `left`, `right`, `center`. Default `center`.
header_font_size	Number	No	Header font size. Default 12, maximum 24, minimum 8. Falls back to `font_size` if unset.
footer_image_size	Number	No	Footer image size. Default 0.1, maximum 1, minimum 0.1.
header_image_size	Number	No	Header image size. Default 0.1, maximum 1, minimum 0.1.

Response

Returns a binary file download containing the stamped PDF. The output schema is a single binary string, so the response body is the generated PDF stream rather than a JSON object.

Body

Name

Type

Description

bodyREQUIRED

object

header_text/header_image (one required) and footer_text/footer_image (one required); if both text and image given for a slot, text wins.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 03 / 04

POST

Stamp header/footer onto an uploaded PDF, get a signed URL back

http://localhost:8080/apyhub/stamp-header-footer-on-pdf/file/url

QUICKSTARTGUIDE

Quickstart

Stamp a PDF from a file upload and return the generated file URL.

curl -X POST "http://localhost:8080/apyhub/stamp-header-footer-on-pdf/file/url" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/input.pdf" \
  -F "header_text=Confidential" \
  -F "footer_text=Page 1"

What you'll get back

Returns a JSON object with a url string field containing the generated file URL.

{
  "url": "https://example.com/stamped.pdf"
}

TRY ITLIVE · 200 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

body*

header_text/header_image (one required) and footer_text/footer_image (one required); if both text and image given for a slot, text wins.

file*

Source PDF file to stamp. Required.

Choose a file…

footer

header

font_size

Shared fallback for header_font_size/footer_font_size.

footer_text

Alias: footer. Required if footer_image not given. Wins over footer_image if both present.

header_text

Alias: header. Required if header_image not given. Wins over header_image if both present.

font_opacity

footer_image

PNG image. Required if footer_text not given.

Choose a file…

header_image

PNG image. Required if header_text not given.

Choose a file…

footer_opacity

header_opacity

Falls back to font_opacity when header_text set, else 1.

footer_alignment

footer_font_size

header_alignment

header_font_size

Falls back to font_size if unset.

footer_image_size

header_image_size

output

About this endpoint

What it does

Stamps a header and/or footer onto an uploaded PDF file and returns a JSON object containing a signed URL for the generated output.

Request Body

Parameter	Type	Mandatory	Description
file	String	Yes	Source PDF file to stamp. Required.
footer	String	No	Footer content.
header	String	No	Header content.
font_size	Number	No	Shared fallback for `header_font_size` and `footer_font_size`. Maximum 24, minimum 8.
footer_text	String	No	Alias for `footer`. Required if `footer_image` is not given. Takes precedence over `footer_image` if both are present.
header_text	String	No	Alias for `header`. Required if `header_image` is not given. Takes precedence over `header_image` if both are present.
font_opacity	Number	No	Opacity for font-based text. Maximum 1, minimum 0.
footer_image	String	No	PNG image. Required if `footer_text` is not given.
header_image	String	No	PNG image. Required if `header_text` is not given.
footer_opacity	Number	No	Default: 1. Maximum 1, minimum 0.
header_opacity	Number	No	Default: 1. Maximum 1, minimum 0. Falls back to `font_opacity` when `header_text` is set; otherwise defaults to 1.
footer_alignment	ENUM	No	Allowed values: `left`, `right`, `center`. Default: `center`.
footer_font_size	Number	No	Default: 12. Maximum 24, minimum 8.
header_alignment	ENUM	No	Allowed values: `left`, `right`, `center`. Default: `center`.
header_font_size	Number	No	Default: 12. Maximum 24, minimum 8. Falls back to `font_size` if unset.
footer_image_size	Number	No	Default: 0.1. Maximum 1, minimum 0.1.
header_image_size	Number	No	Default: 0.1. Maximum 1, minimum 0.1.

Response

Returns a JSON object with a url string field formatted as a URI.

Attribute	Type	Mandatory	Description
url	String	No	Signed URL of the generated PDF output.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

DEFAULT test-sample

Body

Name

Type

Description

bodyREQUIRED

object

header_text/header_image (one required) and footer_text/footer_image (one required); if both text and image given for a slot, text wins.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 04 / 04

POST

Stamp header/footer onto a PDF fetched from a URL, stream result back

http://localhost:8080/apyhub/stamp-header-footer-on-pdf/url/download

QUICKSTARTGUIDE

Quickstart

Generate a PDF from a source file URL with a header and footer in one request.

curl -X POST "http://localhost:8080/apyhub/stamp-header-footer-on-pdf/url/download" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/sample.pdf",
    "header_text": "Confidential",
    "footer_text": "Page footer"
  }'

What you'll get back

Returns the generated PDF as a binary file response.

TRY ITLIVE · 200 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Stamps a PDF fetched from a URL with header and/or footer content, then streams the processed PDF back in the response. The request body must include file_url, and must provide one header source (header_text or header_image_url) and one footer source (footer_text or footer_image_url).

Request Body

Parameter	Type	Mandatory	Description
file_url	String	Yes	URL of the source PDF. Must be a URI.
footer	String	No	Additional footer content field defined by the schema.
header	String	No	Additional header content field defined by the schema.
font_size	Number	No	Font size. Minimum 8, maximum 24.
footer_text	String	No	Footer text content. Use with `footer_image_url` as an alternative footer source; one of these is required for the footer.
header_text	String	No	Header text content. Use with `header_image_url` as an alternative header source; one of these is required for the header.
font_opacity	Number	No	Font opacity. Minimum 0, maximum 1.
footer_opacity	Number	No	Footer opacity. Default: 1. Minimum 0, maximum 1.
header_opacity	Number	No	Header opacity. Default: 1. Minimum 0, maximum 1.
footer_alignment	ENUM	No	Footer alignment. Allowed values: `left`, `right`, `center`. Default: `center`.
footer_font_size	Number	No	Footer font size. Default: 12. Minimum 8, maximum 24.
footer_image_url	String	No	URL of a PNG image. Use with `footer_text` as an alternative footer source; one of these is required for the footer. Must be a URI.
header_alignment	ENUM	No	Header alignment. Allowed values: `left`, `right`, `center`. Default: `center`.
header_font_size	Number	No	Header font size. Default: 12. Minimum 8, maximum 24.
header_image_url	String	No	URL of a PNG image. Use with `header_text` as an alternative header source; one of these is required for the header. Must be a URI.
footer_image_size	Number	No	Footer image size. Default: 0.1. Minimum 0.1, maximum 1.
header_image_size	Number	No	Header image size. Default: 0.1. Minimum 0.1, maximum 1.

Response

Returns a binary response body containing the stamped PDF stream.

Notes

The body schema requires file_url, and the schema also indicates conditional requirements: either header_text or header_image_url must be provided for the header, and either footer_text or footer_image_url must be provided for the footer. Several layout fields have defaults, including header_alignment/footer_alignment set to center, header_font_size/footer_font_size set to 12, header_opacity/footer_opacity set to 1, and header_image_size/footer_image_size set to 0.1.

Body

Name

Type

Description

bodyREQUIRED

object

header_text/header_image_url (one required) and footer_text/footer_image_url (one required).

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.