REST API

REST API

Everything the UI does goes through these endpoints — a workflow can compare, classify, verify, bake and archive without a human. All requests are multipart/form-data; errors come back as JSON {"error": "…"} with a 4xx/422 status and a plain-language message. Interactive OpenAPI docs (Swagger UI, springdoc) are available on the running server.

POST /api/compare — compare two documents

curl -f -o redline.docx \
  -F "original=@BOP NY LCS initial.xlsx" \
  -F "revised=@BOP NY LCS final.xlsx" \
  -F "renderMode=tracked" \
  https://redline.your-domain.com/api/compare

Response: the produced file (content type follows it — docx or xlsx), plus headers:

The produced file also embeds pleodox/change-set.json (machine-readable change list), pleodox/metadata.json (extracted filing metadata + assertion verdicts) and pleodox/integrity.json (per-part SHA-256 manifest, HMAC-signed when the server has a secret). A docx/xlsx is a zip: unzip -p out.docx pleodox/change-set.json.

POST /api/verify — prove a produced file

curl -F "document=@redline.docx" https://redline.your-domain.com/api/verify
# {"integrity":"ok","origin":"ok","partsChecked":22,"failedParts":[],
#  "changeSet":"{...}","metadata":"{...}","sha256":"..."}

integrity: ok | failed | missing | malformed. origin: ok | failed | unsigned | not-configured | absent — see Verify & Bake for what each verdict means.

POST /api/bake — flatten an existing tracked-changes document

Response: the baked .docx, with the same style of response headers.

POST /api/classify — classify a single document

Checks and seals one document (no pair): metadata extraction + assertions in single-document mode, the configured scrub policy, the embedded classification record and integrity manifest — with a runtime proof that the content is untouched. See The Classify page for the flow.

curl -f -o "Classified filing.xlsx" \
  -F "document=@filing.xlsx" -F "profile=NY BOP" \
  https://redline.your-domain.com/api/classify

Response: the sealed copy (Classified <name>), with the shared headers (X-Compare-Verified here means content untouched, plus X-Compare-Warnings, X-Compare-Output-SHA256, X-Compare-Duration-Ms) and one of its own:

Assertions that require two documents (expect: changed|unchanged) are skipped and recorded as skipped. Failed assertions are findings in X-Classify-Report / X-Compare-Warnings and in the embedded pleodox/metadata.json — they never block the download; the receiving system decides.

Alfresco endpoints

These forward the caller's Authorization / Cookie headers to Alfresco — API callers must supply valid Alfresco credentials/session headers themselves; the app stores none.

POST /share/compare

Same options as /api/compare (including outputFormat, colors and changedPagesOnly), but each input side is either an Alfresco version or an uploaded file:

# stored v3.0 vs. a local draft
curl -f -o redline.docx -H "Authorization: Basic …" \
  -F "nodeRef=8f2f…" -F "originalVersionId=3.0" \
  -F "revised=@draft.docx" \
  https://redline.your-domain.com/share/compare

POST /share/save

Files a produced output into Alfresco next to the compared document. The uploaded blob is verified against its own embedded integrity manifest first (with compare.integrity.secret configured, only outputs signed by this server pass); it is stored as a new document in the configured save-folder, stamped with mapped filing-metadata properties and linked to the compared node.

Response JSON: savedAs (final name, auto-renamed on collision), nodeId, propertiesSet + propertiesNote (a mis-typed mapping costs the properties, never the filing), linked + linkNote, and shareLink (the saved document's Share page URL, when the Share base is known).

GET /alfresco/{nodeRef}

Renders the version-pick page (HTML) — the entry point linked from Share.

Operational notes

• Upload limits are standard Spring Boot multipart settings (spring.servlet.multipart.max-file-size / max-request-size).
• Concurrency: at most compare.max-concurrent comparisons run at once; excess requests wait up to 30 s, then receive a clear "busy" error (422).
• Timeout: a comparison exceeding compare.timeout is cancelled promptly and returns a clear error.
• Errors are always JSON {"error": "…"} — user-actionable messages, e.g. "revised sheet 'AOI' print area spans 300 columns; the limit for a Word redline is 256. Shrink the print area to the rate page — or choose the Excel review copy output, which compares whole sheets without a print-area limit."