Quickstart

After the container is running on localhost:8000, you can mask your first text in one call.

Synchronous masking

POST /mask/sync processes the request and returns the final result directly:

curl -s -X POST http://localhost:8000/mask/sync \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      [0, "Patient John Smith, DOB 01/02/1980, called from 555-867-5309.", {}]
    ]
  }'

Each input row is [row_index, text, params]. The response includes one result row per input row. columns[0].deidentified_text holds the masked output:

Patient [PERSON_1], DOB [DATE_TIME_1], called from [PHONE_NUMBER_1].

The entity_ledger maps each placeholder back to the original value. Treat it as sensitive and include it only when your workflow needs review or re-identification.

Batches and parameters

Send multiple rows in one request, with per-row parameters:

curl -s -X POST http://localhost:8000/mask/sync \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      [0, "Call Maria Garcia at 555-867-5309", {"detection_mode": "accurate"}],
      [1, "Maria visited on 2024-03-01", {"threshold": 0.3}]
    ]
  }'

Commonly used parameters include detection_mode, threshold, entities, entity_config, allow_list, language, entity_collapse. See the HTTP API reference.

Asynchronous masking

For large batches, submit with POST /mask and poll with GET /mask.

Submit the batch. This example sets compress_results: false so the polled result is readable:

curl -s -X POST http://localhost:8000/mask \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      [0, "John Smith called jane@example.com", {"compress_results": false}]
    ]
  }'

{
  "status": "processing",
  "query_id": "018f4d6a-8f6e-7b1a-a6d7-7ef8b9d7a001",
  "batch_id": "7b89352a-3a7f-4729-950b-c6f63d7fbf5c"
}

Copy query_id and batch_id, then poll with the Agent Mask headers:

curl -s http://localhost:8000/mask \
  -H "x-agent-mask-query-id: 018f4d6a-8f6e-7b1a-a6d7-7ef8b9d7a001" \
  -H "x-agent-mask-batch-id: 7b89352a-3a7f-4729-950b-c6f63d7fbf5c"

202 means the batch is still running:

{"status": "processing"}

Poll again until the response is 200. The final response has the same shape as the synchronous response:

{
  "data": [
    [
      0,
      {
        "columns": [
          {
            "index": 0,
            "deidentified_text": "[PERSON_1] called [EMAIL_ADDRESS_1]",
            "analyzer_results": []
          }
        ],
        "entity_ledger": [
          {"placeholder": "[PERSON_1]", "text": "John Smith"}
        ]
      }
    ]
  ]
}

The older Snowflake header names are accepted as backwards-compatible aliases, but self-hosted clients should use x-agent-mask-query-id and x-agent-mask-batch-id.

Documents

PDFs, DOCX, images, DICOM files, and ZIP archives are submitted in the same row format: zlib-compress the raw bytes, base64-encode them, and send the string as the row text. The service auto-detects the format, extracts text, and can return redacted files for visual formats when you set include_redacted_document.