Integrations

Integrations connect Stirling PDF to other services: storage to read from and deliver to, virus and data scanners, audit logs, chat and email notifications, and any HTTP API. Save a connection once under Processor → Integrations, then use it in sources and pipelines.

Connect a service#

1. Open Processor → Integrations, find the service, and select Connect.
2. Give the connection a name and enter its address and credentials.
3. Save. The connection is now ready to use, and the Works with column shows where.

Use an integration in a pipeline#

Storage services work differently: choose them when you connect a source, to read documents from them or deliver results to them.

Security steps can stop a run: if a scan finds a problem, the document is held back and appears in Review. Notification, email, and audit steps leave the document unchanged.

Available integrations#

Coming soon: SharePoint, OneDrive, Google Drive, Dropbox, Box, and email inboxes.

Messages and audit events can include details from the document and the run, such as {{document.filename}} and {{run.policyName}}. See Placeholders.

Custom API#

Use Custom API to call a service that has no ready-made integration, such as an internal records system or a review queue.

1. Create a Custom API connection with the service's Base URL and Authentication: a bearer token, a username and password, a token in a custom header, logging in for a token, or none.
2. In the pipeline builder, select Add a tool → Send to another system → Call a custom API, and choose the connection under Account.
3. Enter the Path and Method. The path is added to the connection's base URL and can never reach another host.
4. Choose How to send the document: as a file upload (multipart), inside a JSON payload, or as raw file bytes.
5. Choose What to do with the reply: keep the document and record the reply, or replace the document with what comes back.

For example, a JSON body that sends the file with its name:

{
  "name": "{{document.filename}}",
  "content": "{{document.base64}}"
}

Only administrators can create and edit Custom API connections. Test runs also call the service, so point new pipelines at a test environment first.

Placeholders#

Paths, headers, messages, and JSON bodies can include these values, filled in for each document:

Storage connection settings#

Inputs need read permission, destinations need write permission, and Delete the file mode also needs delete permission.

For S3 Object Lock, use a bucket configured to support it and set both objectLockMode (GOVERNANCE or COMPLIANCE) and retentionDays in the connection options.

RAG databases#

Save the database connection, then create a RAG database destination with its collection and provider-specific options. Select that destination in Ingestion. The database generates embeddings for the chunks it receives.

Administrator settings#

Connection secrets are encrypted at rest. Back up the encryption key with your deployment. Set STIRLING_CREDENTIAL_ENCRYPTION_KEY to use a shared key across nodes; a single-node installation can use its generated credential-encryption.key file.

Restart Stirling PDF after changing them.

For example, to allow an API gateway on your internal network:

POLICIES_ALLOWPRIVATEAPIENDPOINTS=true

services:
  stirling-pdf:
    environment:
      POLICIES_ALLOWPRIVATEAPIENDPOINTS: "true"

See Sources for folder and webhook settings, and Clustering for shared deployment configuration.