Updating the condition format in the API, CLI, and Terraform
Warning
Starting June 9, 2026, Yandex SmartCaptcha will migrate to the new format of conditions and field names in captcha display rules. If using the API, CLI, or Terraform, update your commands and configurations.
Earlier, multiple values in the host condition were provided as a list. Now you need to combine such values into a single text field, separated by |.
The hosts field is also renamed to host_matcher.
Updating current configurations
All rules created in the old format will be automatically migrated to the new one. Your current settings will continue to apply correctly.
Condition description format
|
Old format |
New format |
|
|
example\.com|example\.net |
If the old configuration uses different condition types for this field, combine them into a regular expression.
Example of different condition types in the old format:
exact_match = example.com
exact_not_match = example.net
Example of combining conditions in the new format:
"pireRegexMatch": "example\.com|~(example\.net)"
If in your regular expression the special characters (, ), {, }, [, ], ., *, +, ?, ^, $, |, \, &, or ~ are used as regular characters, escape them with \.
The ~ symbol can be used as logical negation.
Updating the CLI
-
Update the CLI to the latest version:
yc components update -
View the new field format in the
createandupdatecommands:yc smartcaptcha captcha create -h yc smartcaptcha captcha update -h
Examples of using the new field
If you specify display rules in a command, use the new format:
yc smartcaptcha captcha create \
--name captcha \
--security-rules '[
{
name = "captcha-rule",
priority = 1,
condition = {
host = {
host-matcher = {
match = {
pire-regex-match = "example.com|example.net"
}
}
}
}
}
]'
If you store captcha display rules in a YAML file, update the host condition field for the --security-rules-file parameter.
For more information about the commands, see the CLI reference: captcha create and captcha update.
In the Terraform configuration, replace the hosts section with host_matcher:
resource "yandex_smartcaptcha_captcha" "yandex-smartcaptcha-captcha" {
name = "test-terraform-yandex-smartcaptcha-captcha"
security_rule {
name = "rule-condition-migration"
priority = 1
condition {
host {
host_matcher {
pire_regex_match = "a|b"
}
}
}
}
}
For more on yandex_smartcaptcha_captcha properties, see this provider guide.
Example of a request with the new field:
curl -X POST \
'https://smartcaptcha.api.cloud.yandex.net/smartcaptcha/v1/captchas' \
-H "Authorization: Bearer $(yc iam create-token)" \
-H 'Content-Type: application/json' \
-d '{
"folderId": "<folder_ID>",
"name": "captcha",
"securityRules": [
{
"name": "captcha-rule",
"priority": 1,
"condition": {
"host": {
"hostMatcher": {
"pireRegexMatch": "a|b"
}
}
}
}
]
}'
For more on methods, see the REST API reference: Captcha.Create and Captcha.Update for the Captcha resource.