# Mask text

Detects personal data in the given text and masks it according to the selected transform. The default transform is `placeholder` (a reversible placeholder).

POST `/mask`

## Request body

required `application/json`

`text` string required

The raw text to mask.

`transform` string

`placeholder` (reversible `<CATEGORY_N>`), `mask` (length-preserving `####`, irreversible).

default: "placeholder"

Allowed: `placeholder` `mask`

`mask_char` string

Fill character for transform=mask.

default: "#"

`return_vault` boolean

Returns the placeholder to original value mapping (sensitive! off by default, never logged).

default: false

`categories` object

Category filtering: `{preset, enable:[...], disable:[...]}`. preset values: ALL, IDENTITY, IDENTIFIERS, KVKK, KVKK_SENSITIVE. (KVKK = full scope; KVKK_SENSITIVE = only the Article 6 special categories.)

`allow_patterns` string[]

A list of regular expressions (Python `re` syntax) that exempt matches from masking (an allowlist). If the surface text of a detected field matches one of the patterns, that field is NOT masked. Use it when a public value such as an organization name is mistakenly taken for personal data. An invalid pattern returns 422. **Limits:** at most 25 patterns, at most 200 characters per pattern. There is a time budget for scanning. If an exemption pattern exceeds the budget it is NOT applied and the request completes normally: a rule that reduces masking should not take effect under uncertainty.

`block_patterns` string | object[]

A list of regular expressions; every matching piece of text is FORCE-masked even if the model did not detect it. Use it to guarantee identifiers specific to you, such as an internal registry or file number. A plain string gets the category `custom`; a `{pattern, category}` object assigns the category. A match that overlaps an existing detection is skipped (the detection wins). An invalid pattern returns 422. **Limits:** at most 25 patterns, at most 200 characters per pattern. There is a time budget for scanning; if the budget is exceeded the request returns 422. We prefer rejecting the request over silently masking less than we should. **Organization patterns:** the patterns defined for your organization in the panel are ADDED to the ones in this request and cannot be dropped by the request body. The result can only increase masking.

Array of `string | object`

One of:

string

`string`

object

`pattern` string required

Regular expression (Python `re` syntax).

`category` string

Category to assign to the forced field (default `custom`).

## Responses

200 Masking result

`masked_text` string

The masked text.

`transform` string

`spans` Span[]

Array of `Span`

`category` string

`start` integer

`end` integer

`score` number

`timings_ms` object

Total processing time (ms): only { total }.

`vault` object

If return_vault=true, the placeholder to original mapping (sensitive).

401 Missing or invalid virtual key

`detail` string

413 Text exceeded the maximum length (split it or use /mask/batch)

422 Invalid request body

`detail` ValidationError[]

Array of `ValidationError`

`loc` string | integer[]

Array of `string | integer`

Any of:

string

`string`

integer

`integer`

`msg` string

`type` string

### Request

#### python

```
import requests

response = requests.post(
    "https://gw-tr.gurubase.io/mask",
    headers={
        "Content-Type": "application/json"
    },
    json={
  "text": "Ahmet Yılmaz, TC 10000000214.",
  "transform": "placeholder",
  "mask_char": "#",
  "return_vault": False,
  "categories": {},
  "allow_patterns": [
    "\\bDemo Kurum\\b"
  ],
  "block_patterns": [
    "\\bPRJ-\\d{4}\\b",
    {
      "pattern": "\\bSICIL-\\d{6}\\b",
      "category": "custom"
    }
  ]
},
)
```

#### curl

```
curl -X POST "https://gw-tr.gurubase.io/mask" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Ahmet Yılmaz, TC 10000000214.",
  "transform": "placeholder",
  "mask_char": "#",
  "return_vault": false,
  "categories": {},
  "allow_patterns": [
    "\\bDemo Kurum\\b"
  ],
  "block_patterns": [
    "\\bPRJ-\\d{4}\\b",
    {
      "pattern": "\\bSICIL-\\d{6}\\b",
      "category": "custom"
    }
  ]
}'
```

#### js

```
const response = await fetch("https://gw-tr.gurubase.io/mask", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "text": "Ahmet Yılmaz, TC 10000000214.",
  "transform": "placeholder",
  "mask_char": "#",
  "return_vault": false,
  "categories": {},
  "allow_patterns": [
    "\\bDemo Kurum\\b"
  ],
  "block_patterns": [
    "\\bPRJ-\\d{4}\\b",
    {
      "pattern": "\\bSICIL-\\d{6}\\b",
      "category": "custom"
    }
  ]
})
});
```

### Response

#### 200

```
{
  "masked_text": "string",
  "transform": "string",
  "spans": [
    {
      "category": "person",
      "start": 0,
      "end": 0,
      "score": 0.85
    }
  ],
  "timings_ms": {},
  "vault": {}
}
```

#### 401

```
{
  "detail": "string"
}
```

#### 413

Text exceeded the maximum length (split it or use /mask/batch)

#### 422

```
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```