Documents and images · Salus docs

The file endpoint. PDF, DOCX, XLSX and PPTX come back protected in place. Images and scanned pages are read by the optional OCR service.

Request

POST /v1/detect/file with Content-Type: multipart/form-data. The file goes in a part named file; context_id and prompt_id may be sent as additional text parts.

curl -fsS "$SALUS_BASE_URL/v1/detect/file" \
  -H "Authorization: Bearer $SALUS_API_KEY" \
  -F "[email protected]" \
  -F "context_id=ticket-48213"

The redaction mode cannot be chosen per file; the server default applies.

Supported formats

Format	Detected by	What comes back
Plain text (UTF-8)	Valid UTF-8	`redacted_text`
PDF	`%PDF-` header	`redacted_file` as `application/pdf`; each span carries its `page`
DOCX	ZIP containing `word/`	`redacted_file` with the DOCX media type
XLSX	ZIP containing `xl/`	`redacted_file`; inline and shared strings both covered
PPTX	ZIP containing `ppt/`	`redacted_file`; slides and speaker notes
PNG, JPEG	Image magic bytes	Spans and `redacted_text` via OCR (OCR service required)

Anything else returns 415 UNSUPPORTED_MEDIA_TYPE. A file that matches a format but cannot be parsed returns 422.

What “in place” means

Office documents are rewritten inside the original package: the detected text runs are replaced with tokens and everything else, formatting, tables, headers, footers, footnotes, comments and notes, is left as it was. The redacted file arrives as redacted_file.data_base64 with its media_type and file_name, in the same response as the span list.

For PDFs the original glyphs are removed from the page. In vault mode the token is drawn back in a standard font, so the protected PDF reads naturally. In FPE mode, and for values with non-Latin characters, a black box is drawn instead. If a single span cannot be placed on the page, no redacted PDF is returned at all; the spans and the protected text are still returned, with a warning in stats.warnings. A partially redacted file is never produced.

Scanned pages and images

A page counts as scanned when an image covers at least half of it, or when it has an image and no text. With the OCR service enabled, scanned pages and image uploads are rasterised and read on your servers, and the recognised text goes through the same detection as any text. A mixed PDF sends only its scanned pages to OCR.

The OCR channel is block-on-detect: the response carries the spans and the protected text so your application can decide, but no redacted file. Images are never rewritten. stats.warnings states how many pages were read and by which engine.

With the OCR service disabled, an image or an image-only PDF returns 422, and a mixed PDF is processed from its text layer only.

OCR limits per request: 20 pages, 60 seconds per page, 2,500 recognised tokens per page, 32 MiB per file. A page that cannot be read reliably fails the request with 422 rather than returning a partial result.

Size and time

The request body limit is 16 MiB, raised to 33 MiB by the chart when OCR is enabled. File processing is synchronous; the gateway’s upstream timeout is extended to cover the OCR page budget when OCR is on.