Developer docs

Documents API

Documents API reference: download the redacted PDF, and for pseudonymized documents the text version (output.md) and the tag to original correspondence table.

Documents API

Use the Documents API to download redacted outputs, and for pseudonymized documents their text version and correspondence table.

GET /v1/documents/{doc_id}/output

Download the redacted PDF for a successfully processed document.

Headers

  • X-API-Key (required)

Path params

  • doc_id (required, UUID)

cURL example

curl -sS -L "https://www.redact-pdf.ai/v1/documents/DOC_ID/output" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o redacted.pdf

Success

  • HTTP 200
  • Content-Type: application/pdf
  • Response body: binary PDF data

Failure cases

  • 401: missing or invalid key
  • 404: document not found or output not ready

GET /v1/documents/{doc_id}/output.md

The pseudonymized document as Markdown: one ## Page N section per page, every tag in place ([Person 1], or your rename such as [Seller]), black boxes as a block. Only for jobs created with mode=pseudonymize.

curl -sS -D headers.txt "https://www.redact-pdf.ai/v1/documents/DOC_ID/output.md" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o document.md
  • HTTP 200, Content-Type text/markdown
  • X-Text-Version header: a 16-character id of the output this text describes. It changes when the document is edited or detected again in the Studio. Pass it as text_version to the correspondence route when you put the names back into text written from this output.
  • 402: not enough credits (same gate as the PDF)
  • 404: not found, not redacted yet, not a pseudonymize job, or no text version for this output
  • 409: the document was edited in the Studio after this text was produced; the PDF is current, the text is not

GET /v1/documents/{doc_id}/correspondence

The tag → original table of a pseudonymized document, as CSV (UTF-8 with BOM): one row per tag with placeholder, label (your rename, or empty), category and original.

curl -sS "https://www.redact-pdf.ai/v1/documents/DOC_ID/correspondence?text_version=TEXT_VERSION" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o correspondence.csv
  • text_version (optional query param): the X-Text-Version of the output.md you are restoring into. If the output changed since, you get 412 (text_changed) instead of a table whose tags may now stand for other names.
  • 402: not enough credits
  • 404: not found, not redacted yet, or not a pseudonymize job
  • 409: edited in the Studio after the output was produced; download it again from the Studio
  • 422: some tags have no stored original (analysed in redact mode before being pseudonymized)

The table re-identifies the document: keep it on your side. See the Pseudonymize guide.

GET /v1/documents/{doc_id}/entities

What a document's masks cover, as JSON: for a detect-only job, what a redaction would remove; for a redacted document, what was removed (the current masks, Studio edits included).

curl -sS "https://www.redact-pdf.ai/v1/documents/DOC_ID/entities" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "document_id": "7f4f4f85-6b7a-4f88-9a8a-7b9a6a2d2fd0",
  "job_id": "b3f2b2e0-6f30-4f3e-8a7b-2f2a20a7d91c",
  "status": "detected",
  "mode": "redact",
  "page_count": 4,
  "entity_count": 3,
  "box_count": 7,
  "counts": { "Email": 1, "Person": 2 },
  "pages_by_category": { "Email": [4], "Person": [1, 3] },
  "coordinates": { "unit": "pt", "origin": "top-left", "frame": "page as displayed" },
  "text_included": false,
  "note": null,
  "entities": [
    {
      "id": "3c1f…",
      "category": "Person",
      "tag": null,
      "source": "auto",
      "pages": [1, 3],
      "box_count": 4,
      "boxes": [{ "page": 1, "x": 72.0, "y": 140.5, "width": 38.2, "height": 9.6 }],
      "text": null
    }
  ]
}
  • One entity is one person, organization, address… An entity usually covers several word boxes; box_count counts boxes, entity_count counts entities.
  • id is opaque and stable for the document (a keyed hash, never the text). tag is set in pseudonymize mode ([Person 1]).
  • Boxes are in PDF points, origin at the top-left of the page as displayed.
  • Detected text is not returned by default. include_text=true adds text only for documents processed with mode=pseudonymize, the only ones whose detected text is stored (it fills the correspondence table). For other documents text stays null and note says why. include_text is refused (403) to the hosted AI connector, so names never reach a model through it.
  • 402: not enough credits · 404: not found, not finished, or files deleted
  • Sent with Cache-Control: no-store.

Integration tip

Only attempt downloads for documents with status redacted from GET /v1/jobs/{job_id}. A detected document has entities but no PDF until its job is redacted.

Related pages