AI Smart Redact connectors

The AI Smart Redact connectors integrate Conversion Service with Pdftools AI Smart Redact. They use the AI Smart Redact Orchestrator REST API to schedule redaction jobs and to fetch redacted PDFs back into a workflow.

Conversion Service provides two AI Smart Redact connectors:

• Schedule AI Smart Redact (output connector): Submits each result PDF from a Conversion Service workflow to the Orchestrator as a new redaction job.
• Poll AI Smart Redact (input connector): Periodically checks the Orchestrator for finished redaction jobs, downloads each redacted PDF, and forwards it to a workflow.

Use the connectors together to round-trip documents through AI Smart Redact: the Schedule AI Smart Redact connector hands a PDF to the Orchestrator, and the Poll AI Smart Redact connector later picks up the redacted PDF and feeds it back into a Conversion Service workflow. Use either connector on its own when only one side of the flow is needed.

Schedule AI Smart Redact output connector

The Schedule AI Smart Redact output connector submits each result PDF to the Orchestrator as a new redaction job and returns immediately. Detection, human review, and redaction itself run inside AI Smart Redact, on the Orchestrator’s schedule.

Workflow compatibility

Pair the Schedule AI Smart Redact connector with plain-PDF workflows, such as Convert to PDF.

Don't combine with PDF/A archival workflows

The Schedule AI Smart Redact connector must not run after the Archive PDF/A-1, Archive PDF/A-2, or Archive PDF/A-3 workflows. The downstream redaction step rewrites the PDF content stream, which breaks PDF/A conformance. The redacted PDF no longer qualifies as a PDF/A archive document.

Schedule AI Smart Redact configuration options

• Endpoint: Base URL of the AI Smart Redact Orchestrator. The default is http://localhost:9983. The Configurator rejects empty values and malformed URLs.

• API Key: Pre-provisioned API key sent on every request as the X-Api-Key header. To request a key, contact your AI Smart Redact administrator.

• Job Status: Result status that activates the connector:

  • Success: The connector activates for jobs that complete without warnings.
  • Warnings: The connector activates for jobs that complete with warnings.
  • Success or Warnings: The connector activates for jobs that complete with or without warnings.

  The connector requires a result PDF, which the workflow doesn’t produce when a job fails. The Conversion Service Configurator and the Configurator Web reject Error at save time, and the runtime refuses to start the connector if the configuration sets it.

Poll AI Smart Redact input connector

The Poll AI Smart Redact input connector periodically checks the Orchestrator for redaction jobs scheduled by the Schedule AI Smart Redact connector. When a job finishes, the connector downloads the redacted PDF and forwards it to the configured workflow. The connector checks jobs that are still in progress again on the next poll. The connector logs jobs that the Orchestrator reports as canceled, expired, or failed and never forwards a PDF for them.

The Poll AI Smart Redact connector doesn’t delete jobs from the Orchestrator; AI Smart Redact manages job retention entirely.

Poll AI Smart Redact configuration options

• Endpoint: Base URL of the AI Smart Redact Orchestrator. The default is http://localhost:9983. The Configurator rejects empty values and malformed URLs.
• API Key: Pre-provisioned API key sent on every request as the X-Api-Key header.
• Poll interval (seconds): Time between poll cycles, in seconds. Defaults to 60. Must be a positive whole number.

Forwarded filename and variables

The connector preserves the original filename from the Orchestrator, when present, on the input item handed to the workflow.

The Poll AI Smart Redact connector exposes two input-scope variables that downstream output connectors can reference, in the same way as the [input:<variable>] placeholders described in Companion file:

Variable	Description
[input:AI_SMART_REDACT_JOB_ID]	Orchestrator job ID, a globally unique identifier (GUID). Useful for correlating downstream artifacts with the source redaction job.
[input:AI_SMART_REDACT_ORIGINAL_NAME]	Original filename as known to the Orchestrator.

Shared connector behavior

Both connectors share the same configuration model, storage rules, and HTTP behavior.

Configurator support

The Conversion Service Configurator and the Configurator Web expose identical fields for both AI Smart Redact connectors, including a masked API Key field. Both Configurator clients validate the same constraints at save time: empty endpoint, malformed URL, empty API key, and Error Job Status for the Schedule AI Smart Redact connector. The Poll AI Smart Redact connector additionally requires the Poll interval (seconds) to be a positive whole number.

The Schedule AI Smart Redact connector appears in the Add Output dialog, and the Poll AI Smart Redact connector appears in the Add Input dialog.

API key storage

The Configurator stores the API key according to the host operating system:

• Windows: Encrypted with the Data Protection API (DPAPI), scoped to the local machine.
• Linux: Stored as plain text. The Data Protection API isn’t available on Linux.

To keep the API key out of stored configuration on Linux or in Docker, set the environment-variable overrides instead.

Environment-variable overrides

Set the following environment variables to override the values stored by the Configurator. Conversion Service reads them at process start, and they take precedence over the stored values. Empty environment-variable values fall back to the stored value.

Variable	Overrides
AI_SMART_REDACT_ENDPOINT	Endpoint URL of the AI Smart Redact Orchestrator.
AI_SMART_REDACT_APIKEY	API key sent in the X-Api-Key header.

tip

Use the environment-variable overrides for Linux and Docker deployments to keep the API key out of stored configuration.

Example: Docker Compose

services:
  conversion-service:
    image: pdftoolsag/conversion-service:${IMAGE_VERSION}
    environment:
      - AI_SMART_REDACT_ENDPOINT=https://smart-redact.example.com
      - AI_SMART_REDACT_APIKEY=${SMART_REDACT_API_KEY}

Set SMART_REDACT_API_KEY in a .env file or your container orchestration secret store. The Configurator’s API key field can stay empty in this setup.

HTTP behavior

• Per-request timeout: 10 minutes, to accommodate large PDF uploads and downloads on slow links.
• Authentication header: X-Api-Key on every request to the Orchestrator.

Error handling

The Schedule AI Smart Redact connector reports errors based on the Orchestrator response to the job-creation request:

Response	Connector behavior	Resolution
201 Created	The Orchestrator accepted the job. The connector logs the job ID.	None.
401 Unauthorized	The connector raises a hard error: “Smart Redact orchestrator rejected the API key (401). Contact the Smart Redact team for a new key.”	Request a new API key from your AI Smart Redact administrator and update the connector configuration or environment variable.
403 Forbidden	The connector raises a hard error: “Smart Redact orchestrator refused the call (403). Verify the Smart Redact license is valid.”	Verify the AI Smart Redact license on the Orchestrator.

The Poll AI Smart Redact connector catches 401 and 403 responses during polling and logs them. Polling pauses until the next interval; the connector doesn’t fail on authentication or authorization errors.