ZIP Archives

Agent Mask can process a ZIP archive as one input column. The archive is validated, supported entries are extracted, each processed entry is de-identified, and the response is returned under columns[].archive.

Compress the raw ZIP bytes with zlib, then base64-encode the compressed bytes before passing them to mask().

Supported entries

Archive entries are processed when they match one of the supported document formats or can be decoded as UTF-8 text:

PDF, including scanned PDFs
DOCX
RTF
DICOM
PNG, JPEG, or TIFF
UTF-8 text files such as .txt, .csv, .log, or .md

Unsupported binary files are listed in skipped_files. Nested ZIP archives, entries that cannot be read, entries that fail extraction, and entries that exceed per-entry limits are also skipped. Directories and common hidden or system entries are ignored.

If no entries can be extracted, the request returns an error instead of an empty archive result.

Quick example

Set include_redacted_document only when you need redacted binary output for entries that support it.

SELECT app_public.mask(
  '<compressed_base64_zip>',
  OBJECT_CONSTRUCT(
    'include_redacted_document', TRUE
  )
);

Response shape

{
  "columns": [
    {
      "index": 0,
      "archive": {
        "documents": [
          {
            "filename": "forms/intake.pdf",
            "deidentified_text": "Patient [PERSON_1]",
            "metadata": {"file_type": "pdf"},
            "redacted_document": "<base64_zlib_pdf_bytes>"
          },
          {
            "filename": "note.txt",
            "deidentified_text": "Patient [PERSON_1]",
            "metadata": {"file_type": "txt"},
            "original_text": "Patient Jane Smith"
          }
        ],
        "skipped_files": [
          {"filename": "scan.bin", "reason": "Unsupported file type"},
          {"filename": "nested.zip", "reason": "Nested ZIP archives not supported"}
        ],
        "redacted_archive": "<base64_zip_bytes>"
      }
    }
  ],
  "entity_ledger": [
    {
      "entity_type": "PERSON",
      "original": "Jane Smith",
      "placeholder": "[REDACTED_PERSON_1]",
      "replacement": "[PERSON_1]"
    }
  ]
}

Redacted archive output

When include_redacted_document=true, entries that support binary redaction can include a per-entry redacted_document. These are the ZIP entry types that can produce redacted binaries:

PDF and scanned PDF entries
PNG, JPEG, and TIFF image entries
DICOM entries

Text-only extraction formats, including UTF-8 text files, DOCX, and RTF, return de-identified text in the JSON response but do not return a redacted binary file. Skipped files are not redacted.

If at least one entry returns a redacted_document, the archive object also includes:

{
  "redacted_archive": "<base64_zip_bytes>"
}

redacted_archive is a base64-encoded ZIP containing only entries that produced redacted binary output. It is not a complete copy of the source archive: text-only entries, unsupported entries, skipped entries, and entries that did not produce a redacted binary are omitted.

Review archive.documents[] for each processed entry and archive.skipped_files[] for entries that were not processed before relying on a redacted archive in downstream workflows.

Safety limits

Agent Mask rejects archives with encrypted entries, unsafe paths, too many extractable entries, oversized declared entries, oversized total decompressed data, or suspicious compression ratios. Individual files can also be skipped when they are unsupported, unreadable, too large at extraction time, or fail extraction.

Treat review metadata as sensitive when you enable it. entity_ledger, analyzer_results, original_text, and extracted document text can include source values or span details.