Mask-only usage

Using the Siper /mask endpoint directly. Transform options, batch requests, category filtering, and regex 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 API 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; direct masking endpoints use raw category names in placeholders (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. All fields are in the Mask text reference.

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. For the schema, see the Mask in batch reference.

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 32 categories, including the 3 secret categories such as API keys. 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.

Regex lists

Two list fields let you add your own rules to the masking decision. Both take a list of regular expressions (Python re syntax); if a list holds an invalid expression, the request returns 422.

• allow_patterns: if the surface text of a detected span matches an expression in the list, 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 an expression in the list 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.