Mask-only usage

Using the Siper /mask endpoint directly. Transform options, batch requests, category filtering, and pattern lists.

You can also use masking without a language model, as a step in your own pipeline. The /mask endpoint takes text and returns the masked text together with a detection report that shows what was found in which range.

You authorize requests with the virtual key you generate in the panel, sent in the Authorization: Bearer header; it is the same key you use for Gateway calls. /mask calls are also subject to request limits and the audit trail.

Body errors (missing or malformed requests) and authentication errors are returned in the Gateway’s error format; field validation details may arrive in the masking service’s own format.

First call

curl https://gw-tr.gurubase.io/mask \
  -H "Authorization: Bearer $SANAL_ANAHTAR" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ahmet Yılmaz, TCKN 10000000382, İstanbul'\''da yaşıyor."}'

{
  "masked_text": "<PERSON_1>, TCKN <TCKN_1>, İstanbul'da yaşıyor.",
  "transform": "placeholder",
  "spans": [
    { "category": "person", "start": 0, "end": 12, "score": 0.85 },
    { "category": "tckn", "start": 19, "end": 30, "score": 1.0 }
  ],
  "timings_ms": { "total": 27.58 }
}

masked_text is the masked text; placeholders in the API are in English (Concepts). The spans list gives, for each detection, the category, the character range in the input text (start, end), and the confidence score (score). timings_ms.total is the total processing time.

Transform options

The transform field determines the shape of the masked text; the default is placeholder.

Batch requests

You send multiple texts to the /mask/batch endpoint in a single request; the results array is returned in the same order as the input. For text that exceeds the length limit, /mask returns 413. On /mask/batch, this limit is applied to the combined total text.

curl https://gw-tr.gurubase.io/mask/batch \
  -H "Authorization: Bearer $SANAL_ANAHTAR" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "Ahmet Yılmaz aradı.",
      "IBAN: TR12 0001 0000 0000 0000 0000 01"
    ]
  }'

Category filtering

The default behavior is to mask all 26 categories. You narrow the scope with the categories field: you pick a preset, and if needed the enable list adds categories to the set while disable removes them. Category keys are the same as the category values in the report (such as person, tckn, saglik).

{
  "text": "...",
  "categories": { "preset": "KVKK_SENSITIVE" }
}

For the full list of categories and the Article 6 distinction, see Categories.

Pattern lists

With two list fields, you add your own rules to the masking decision. Both take a list of regular expressions (Python re syntax); an invalid pattern returns 422.

• allow_patterns: if the surface text of a detected span matches a pattern, that span is not masked. Useful for fixed values that are not personal data; for example, you do not want your shared support address or your organization’s name to be masked.
• block_patterns: every piece of text that matches a pattern is masked, even if the model did not detect it. Use it to lock in organization-specific registry, file, or customer number formats. If you pass a plain string, the category is custom; with a {"pattern": ..., "category": ...} object you assign a category. A match that overlaps an existing detection is skipped; the detection wins.

{
  "text": "...",
  "allow_patterns": ["destek@kurum\\.example", "\\bDemo Kurum\\b"],
  "block_patterns": [
    "\\bMST-\\d{6}\\b",
    { "pattern": "\\bSICIL-\\d{6}\\b", "category": "custom" }
  ]
}

For the placeholder format and the language distinction, see Concepts. To use the same masking inside a chat flow, see Gateway integration.