Document Operations

Status: Available · Spec: openapi/doc-ops.yaml · Base URL: issued by your platform operator (local/companion port 9190)

The document toolbox: 20+ operations over PDF and Office formats — convert, merge, split, compress, OCR, watermark, redact, sanitize, PDF/A, extraction, diffing, and more — all behind one asynchronous job model. Where Prism creates documents from data, Document Operations transforms documents you already have.

Auth & tenancy: Bearer token (machine-to-machine JWT or tenant API key); tenant via the X-Tenant-ID header on every call.

The job model — one pattern for every operation

Every operation is submit-then-poll (conventions):

Submit — POST /v1/{operation} with a multipart/form-data upload (file(s) + operation parameters). Returns immediately: json { "ok": true, "data": { "job_id": "…", "status": "pending" } }
Poll — GET /v1/jobs/{job_id} until completed or failed. Failures carry a coded error in the envelope.
Download — GET /v1/jobs/{job_id}/download for the result binary. (Preview: result-download delivery is being finalised — verify availability with your platform contact.)

The operation families

Family	Operations
Convert	Office/HTML/markdown → PDF and related conversions (`convert`)
Assemble	`merge`, `split`
Extract	`extract` (text/pages), `extract_data` (structured), `text_blocks`, `links`, `metadata`
Enhance	`watermark`, `page_numbers`, `qr`, `annotate`, `tag`, `edit_text`
Protect & comply	`encrypt`, `permissions`, `sanitize`, `redact`, `provenance`, `pdfa`
Analyse	`diff`, `ocr`, `compress`, `agent` (instruction-driven document processing)

GET /v1/capabilities returns the machine-readable list of operations and parameters enabled for your tenant — drive feature flags from it rather than hardcoding.

Errors worth handling

400 — blocked or invalid parameters (e.g. disallowed conversion source)
403 — operation mode disabled for your tenant (e.g. URL-mode conversion)
422 — validation failure on the multipart payload
502 — upstream conversion failure; retry with backoff, then surface to the operator

Integration notes

One client wrapper, many operations. Since every operation shares the submit/poll/download shape, write the job-lifecycle handling once.
Chain via your backend. Multi-step flows (convert → watermark → PDF/A) are your orchestration: feed each completed job's output into the next submission — or use the agent operation for instruction-driven processing.
Compliance operations are first-class. sanitize, redact, and pdfa exist for document-handling obligations — prefer them over ad-hoc client-side manipulation.