Inputs and configuration

JSON text

Provide a text string and an optional config object. Unknown top-level fields are rejected. Text must contain at least one non-whitespace character.

{
  "text": "Text to inspect",
  "config": {
    "categories": ["injection", "dlp"],
    "max_level": "L3"
  }
}

TextScan

Field	Type	Details
text	string	Required. Non-empty UTF-8 text. Whitespace-only input is rejected.
config	ScanConfig	Optional.

ScanConfig

Field	Type	Details
categories	injection | dlp | pii | threat[]	Optional. Select one to four different categories. Omit to run injection and dlp. Canonical names are lowercase; the API also accepts case-insensitive names and rejects duplicates after normalization. Default: ["injection","dlp"].
max_level	L1 | L2 | L3	Optional. Highest analysis level allowed for this request. Threat detection currently requires at least L2; do not combine threat with L1-only analysis or disable L2. For all four categories, use L3 or leave level and gates unset.
gates	object	Optional. Enable or disable whole analysis levels or select individual rules/models. All switches must be booleans. Leave unset for service defaults.

Choose categories

Omitting categories runs both injection and dlp. To request additional checks, select from these four categories:

Category	Checks for
injection	Instructions that may redirect an AI workflow.
dlp	Sensitive data and data leakage signals.
pii	Personally identifiable information.
threat	Threat signals in the submitted content.

{"categories": ["injection", "dlp", "pii", "threat"]}

{"categories": ["dlp"]}

Select one to four different categories. An empty array, duplicates, and other category names are rejected. Names are case-insensitive and normalized to lowercase.

Analysis levels

max_level accepts L1, L2, or L3. Use the boolean gates l1, l2, and l3 to enable or disable whole analysis levels. These settings constrain the analysis; they do not guarantee that every enabled level will run. Leave them unset for the service’s normal routing.

{
  "categories": ["injection", "dlp", "pii"],
  "max_level": "L1",
  "gates": {"l1": true, "l2": false, "l3": false}
}

threat currently requires at least L2. Do not combine it with max_level: "L1" or disable its L2 analysis. For all four categories, use max_level: "L3" or leave the level and gates unset. The L1 example above covers injection, DLP, and PII only.

Individual rules and models

For finer control, gates.rules and gates.models map rule or model IDs to booleans. true enables an item; false disables it. Omit the maps to use service defaults.

See the rules and models catalog for available IDs, categories, analysis levels, and rule defaults. For example, keep PII analysis enabled while excluding email detection:

{
  "categories": ["injection", "dlp", "pii"],
  "max_level": "L1",
  "gates": {
    "l1": true,
    "rules": {"pii_email": false},
    "models": {"native:pii": true}
  }
}

Use the exact catalog IDs. The API validates the map’s shape and forwards it to the scanner; an accepted ID does not confirm that a matching rule or model exists. The maps select existing detectors; they do not define rules or upload models.

Each map accepts up to 512 entries. IDs must contain 1–128 letters, digits, or the characters _, :, ., /, and -. The names __proto__, constructor, and prototype are rejected. Values must be JSON booleans, not strings or numbers.

Restricting levels or disabling detectors changes coverage. Test the configuration on representative inputs before enforcement. The only top-level fields are categories, max_level, and gates; other engine settings are rejected.

Multipart text files

Use multipart/form-data with one or more file parts named files. Repeat the field for multiple files. You may also include a text field. Each text input and file must contain non-empty UTF-8 text.

The optional config part is a JSON string, supplied once. Let your HTTP client set the multipart boundary.

curl --fail-with-body https://control.patronus.studio/api/v1/scan \
  -H "Authorization: Bearer $PATRONUS_API_KEY" \
  -F '[email protected];type=text/plain' \
  -F '[email protected];type=text/plain' \
  -F 'config={"categories":["injection","dlp"]}'

For asynchronous submissions, poll every job in the response. See the complete clients for the full result lifecycle.