Parse PDF, DOCX, TXT, CSV and XLSX documents, detect PII per page, and download a redacted copy.

Extract text from a document, with OCR for scanned pages, scan it for PII and safety issues, and produce a redacted copy you can download later.

Warning

Every /document-analysis route is guarded by the JWT guard alone. A gateway API key (cid_key_…) cannot call these endpoints.

Endpoints

Method	Path	Body
POST	`/document-analysis/analyze`	JSON with base64
POST	`/document-analysis/analyze-file`	Multipart, field name `file`
POST	`/document-analysis/redact-jobs`	Multipart `file`; starts an asynchronous redaction job
GET	`/document-analysis/redact-jobs/:jobId`	Poll a redaction job
GET	`/document-analysis/supported-types`	Parseable types and their OCR support
GET	`/document-analysis/status`	Document-parser reachability
GET	`/document-analysis/:id/download`	Stream the redacted document

Analyse a document (JSON)

POST /document-analysis/analyze

Parameter	Type	Required	Description
`documentBase64`	string	Yes	Base64-encoded document
`documentType`	string	Yes	`pdf`, `docx`, `txt`, `csv` or `xlsx`
`sessionId`	string	No	Log the detections against this session
`redact`	boolean	No	Produce a redacted copy. Default `true`
`parseOptions`	object	No	`ocrScannedPages` (default `true`), `ocrLanguage` (default `en`), `ocrEngine`, `extractTextBlocks` (default `true`), `includeMetadata` (default `true`), `filename`
`processingMode`	string	No	`text` (default) or `visual`
`renderDpi`	number	No	72–300, default `150`. Applies to `visual` mode

curl -X POST https://<appliance-fqdn>/document-analysis/analyze \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "documentBase64": "JVBERi0xLjQK...",
    "documentType": "pdf",
    "redact": true
  }'

Analyse a document (multipart)

POST /document-analysis/analyze-file

The multipart route takes a raw upload instead of base64, which avoids the roughly one-third inflation base64 costs. The file field is named file. The document type is derived from the file extension, so documentType is not sent.

Form field	Required	Description
`file`	Yes	The document. Maximum 20 MB
`redact`	No	The string `false` turns redaction off; anything else leaves it on
`sessionId`	No	Log the detections against this session

curl -X POST https://<appliance-fqdn>/document-analysis/analyze-file \
  -H "Authorization: Bearer <jwt>" \
  -F "file=@statement.xlsx" \
  -F "redact=true"

Extensions

Extension	Parsed as
`.pdf`	`pdf`
`.docx`	`docx`
`.txt`	`txt`
`.csv`, `.tsv`	`csv`
`.xlsx`	`xlsx`

Danger

.xls, .xlsm, .xlsb, .xlt and .xltm are refused with 415. Legacy binary and macro-enabled workbooks cannot be redacted verifiably — a macro can reconstruct data that was painted out — so the gateway blocks them rather than returning a copy it cannot vouch for. Save the file as .xlsx without macros and upload it again.

An unrecognised extension also returns 415, listing the supported ones. A request with no file part returns 400 with No file uploaded (expected multipart field "file").

Response

Both analysis routes return the same shape.

{
  "success": true,
  "analysisId": "a1b2c3d4-0000-0000-0000-000000000000",
  "documentType": "pdf",
  "pageCount": 4,
  "totalWordCount": 1280,
  "action": "mask",
  "detections": [
    { "type": "EMAIL", "value": "[EMAIL]", "action": "mask", "confidence": 0.95, "pageNumber": 1 }
  ],
  "pageResults": [
    { "pageNumber": 1, "wordCount": 320, "isScanned": false, "detectionCount": 3 }
  ],
  "wasRedacted": true,
  "ocrPages": 0,
  "processingTimeMs": 2540
}

Field	Type	Description
`success`	boolean	Whether the analysis completed
`analysisId`	string	Pass this to `/document-analysis/:id/download`
`documentType`, `pageCount`, `totalWordCount`	—	What was parsed
`action`, `actionReason`	string	The decided action and why
`detections`	array	`{type, value, confidence, action, pageNumber?, filterName?, placeholder?}`
`pageResults`	array	Per-page word counts, scanned flag and detection counts
`redactedDocumentBase64`	string	The redacted copy, when one was produced
`wasRedacted`	boolean	Whether redaction ran
`ocrPages`	number	How many pages needed OCR
`extractedText`, `redactedText`	string	Plain-text before and after
`processingMode`	string	`text` or `visual`, as applied
`redactionVerified`	boolean	Whether the redacted copy was checked to no longer contain the detected values
`renderedPages`, `tablePreview`	—	Present for visual mode and spreadsheets
`error`	string	Present when the analysis failed

As on the text path, value carries the placeholder rather than the matched text.

Supported types

GET /document-analysis/supported-types

Returns the types the document parser reports, each with its extensions, MIME types and whether it supports OCR. The gateway answers 503 when the parser service is unreachable, so this endpoint doubles as a health probe for it.

Download a redacted document

GET /document-analysis/:id/download

Streams the redacted document produced by an earlier analysis, addressed by its analysisId.

curl -X GET https://<appliance-fqdn>/document-analysis/a1b2c3d4-0000-0000-0000-000000000000/download \
  -H "Authorization: Bearer <jwt>" \
  -o redacted.pdf

Image analysis — the same pipeline over images, with OCR.
PII detection — which entity types the extracted text is scanned for.
Content detection — the detection contract these responses share.

Document analysis