longrun.
Add Watermark

Docs

PDF actions / Add Watermark

Add Watermark

Use Add Watermark to process your inputs. Submit the request, then retrieve the run to get its result.

POSThttps://uselongrun.app/v1/pdf/watermark
Request
curl --request POST "https://uselongrun.app/v1/pdf/watermark" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data "$(jq -n --arg FILE_ID "${FILE_ID}" '{
  "inputs": {
    "file": $FILE_ID
  }
}')"
Set up your API keyErrors and retries
Accepted · 202
{
  "id": "run_example",
  "status": "queued",
  "outputs": null,
  "error": null,
  "retry_of_run_id": null,
  "created_at": "2026-10-22T10:00:00.000Z",
  "updated_at": "2026-10-22T10:00:00.000Z"
}

The request is accepted, but processing has not finished. Retrieve the run using its ID to get the result.

Completed run · 200
{
  "id": "run_example",
  "status": "completed",
  "outputs": {
    "file": {
      "saved": false,
      "retained": false,
      "id": "file_result",
      "name": "2026-10-22_10-00-03-000.pdf",
      "mime_type": "application/pdf",
      "size": 76800,
      "category": "PDF",
      "storage": "longrun",
      "url": "https://uselongrun.app/v1/files/file_result/content",
      "access": "authenticated",
      "source": "action",
      "created_at": "2026-10-22T10:00:03.000Z",
      "expires_at": "2026-10-23T10:00:03.000Z",
      "expired": false,
      "source_run_id": "run_example",
      "source_name": "Generated file"
    }
  },
  "error": null,
  "retry_of_run_id": null,
  "created_at": "2026-10-22T10:00:00.000Z",
  "updated_at": "2026-10-22T10:00:03.000Z"
}

Example result from Get a run after processing completes. File examples use temporary storage; metadata and values will vary with your inputs.

Get the run result

Request parameters

header
Idempotency-KeystringOptional

Scoped to workspace and operation; same key and payload reuses the run during its seven-day retention period. Changed payload returns 409.

Example
"receipt-1042-v1"

Maximum length: 200 characters.

Request body

Send a JSON body with the following inputs. Put processing settings inside options.

Inputs

inputs.filePDF fileRequired

The PDF file to process. Upload it first and use the returned file ID.

Example
"${FILE_ID}"

Use an uploaded file ID or a supported file reference. Learn how to send files

inputs.overlayImage fileOptional

Image to place over the source as a watermark. Upload it first and use its file ID.

Example
"${WATERMARK_FILE_ID}"

Use an uploaded file ID or a supported file reference. Learn how to send files

Options

options.pagesarray of numberOptional

Page numbers to process. The first page is 1.

Example
[
  1,
  3
]
options.rangestextOptional

Pages to process, expressed as comma-separated numbers or ranges.

Example
"1-3,5"
options.font_sizenumberOptional

Size of the text, in points (72 points = one inch).

Example
24

Minimum: 6

Maximum: 200

options.opacitynumberOptional

Transparency of the watermark: 0 is invisible and 1 is fully opaque.

Example
0.5

Minimum: 0

Maximum: 1

options.xnumberOptional

Horizontal position, in points (72 points = one inch).

Example
20
options.ynumberOptional

Vertical position, in points (72 points = one inch).

Example
20
options.texttextOptional

Text to place on the result.

Example
"Confidential"
options.anglenumberOptional

Rotation angle in degrees.

Example
90

Minimum: -360

Maximum: 360

options.widthnumberOptional

Width of the output or overlay, in points (72 points = one inch).

Example
800

Minimum: 1

Maximum: 14400

Delivery

outputobjectOptional

Choose where the result is delivered. Omit this to use temporary LongRun storage.

Example
{
  "storage": "temporary"
}

Storage guide · Bubble delivery setup

Show child fields
output.storagestringOptional

temporary stores results in LongRun. bubble delivers them to a connected Bubble app. These are the only supported values. A published workflow uses its configured destination unless you override it.

Example
"temporary"

Default: "temporary"

Allowed values: temporary bubble

output.connection_idstringConditionally required

Required when storage is bubble. Copy the connection ID from Settings → Integrations → Bubble. Not used for temporary storage.

Example
"${STORAGE_CONNECTION_ID}"
output.privatebooleanOptional

Only for Bubble delivery. true creates a private file and requires attach_to. false requests a public upload; access still depends on the receiving app configuration.

Example
false

Default: false

output.attach_tostringConditionally required

Required when storage is bubble and private is true. The Bubble Thing ID that owns the file. See the Bubble integration guide for setup.

Example
"${BUBBLE_THING_ID}"
output.file_namestringOptional

Optional output filename, such as receipt.pdf. Omit it to use the generated timestamp-based name. Applies to either destination.

Example
"receipt.pdf"

Maximum length: 255 characters.

webhook_idsarray of stringOptional

IDs of configured webhook endpoints to notify for this run. Omit this to send no webhooks for a direct action.

Example
[
  "${WEBHOOK_ID}"
]

Returns

Returns 202 Accepted with a run ID. Processing continues after the response. Retrieve the run until its status is completed, failed, or cancelled.

Retrieve a run →

Outputs when completed

These fields appear inside outputs on the completed run.

outputs.filePDF file

Generated file metadata. Use its id to retrieve or download the file; check access and expiry metadata before using its URL.

Limits

Input files combined
100 MiB
Generated files
200 MiB maximum
Processing deadline
120 seconds; processing may stop earlier if a renderer or resource limit is reached
options.pages items
100 maximum
Source PDF pages
1,000 maximum