SmartCaptcha API, REST: Captcha.Create

Written by

Updated at October 17, 2024

HTTP request
Body parameters
SecurityRule
Condition
HostMatcher
StringMatcher
UriMatcher
QueryMatcher
HeaderMatcher
IpMatcher
IpRangesMatcher
GeoIpMatcher
OverrideVariant
Response
CreateCaptchaMetadata
Status
Captcha
SecurityRule
Condition
HostMatcher
StringMatcher
UriMatcher
QueryMatcher
HeaderMatcher
IpMatcher
IpRangesMatcher
GeoIpMatcher
OverrideVariant

Creates a captcha in the specified folder using the data specified in the request.

HTTP request

POST https://smartcaptcha.api.cloud.yandex.net/smartcaptcha/v1/captchas

Body parameters

{
  "folderId": "string",
  "name": "string",
  "allowedSites": [
    "string"
  ],
  "complexity": "string",
  "styleJson": "string",
  "turnOffHostnameCheck": "boolean",
  "preCheckType": "string",
  "challengeType": "string",
  "securityRules": [
    {
      "name": "string",
      "priority": "string",
      "description": "string",
      "condition": {
        "host": {
          "hosts": [
            {
              // Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`
              "exactMatch": "string",
              "exactNotMatch": "string",
              "prefixMatch": "string",
              "prefixNotMatch": "string",
              "pireRegexMatch": "string",
              "pireRegexNotMatch": "string"
              // end of the list of possible fields
            }
          ]
        },
        "uri": {
          "path": {
            // Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`
            "exactMatch": "string",
            "exactNotMatch": "string",
            "prefixMatch": "string",
            "prefixNotMatch": "string",
            "pireRegexMatch": "string",
            "pireRegexNotMatch": "string"
            // end of the list of possible fields
          },
          "queries": [
            {
              "key": "string",
              "value": {
                // Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`
                "exactMatch": "string",
                "exactNotMatch": "string",
                "prefixMatch": "string",
                "prefixNotMatch": "string",
                "pireRegexMatch": "string",
                "pireRegexNotMatch": "string"
                // end of the list of possible fields
              }
            }
          ]
        },
        "headers": [
          {
            "name": "string",
            "value": {
              // Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`
              "exactMatch": "string",
              "exactNotMatch": "string",
              "prefixMatch": "string",
              "prefixNotMatch": "string",
              "pireRegexMatch": "string",
              "pireRegexNotMatch": "string"
              // end of the list of possible fields
            }
          }
        ],
        "sourceIp": {
          "ipRangesMatch": {
            "ipRanges": [
              "string"
            ]
          },
          "ipRangesNotMatch": {
            "ipRanges": [
              "string"
            ]
          },
          "geoIpMatch": {
            "locations": [
              "string"
            ]
          },
          "geoIpNotMatch": {
            "locations": [
              "string"
            ]
          }
        }
      },
      "overrideVariantUuid": "string"
    }
  ],
  "deletionProtection": "boolean",
  "overrideVariants": [
    {
      "uuid": "string",
      "description": "string",
      "complexity": "string",
      "preCheckType": "string",
      "challengeType": "string"
    }
  ]
}

Field	Description
folderId	string Required field. ID of the folder to create a captcha in.
name	string Name of the captcha. The name must be unique within the folder.
allowedSites[]	string List of allowed host names, see Domain validation.
complexity	enum (CaptchaComplexity) Complexity of the captcha. `CAPTCHA_COMPLEXITY_UNSPECIFIED` `EASY`: High chance to pass pre-check and easy advanced challenge. `MEDIUM`: Medium chance to pass pre-check and normal advanced challenge. `HARD`: Little chance to pass pre-check and hard advanced challenge. `FORCE_HARD`: Impossible to pass pre-check and hard advanced challenge.
styleJson	string JSON with variables to define the captcha appearance. For more details see generated JSON in cloud console.
turnOffHostnameCheck	boolean Turn off host name check, see Domain validation.
preCheckType	enum (CaptchaPreCheckType) Basic check type of the captcha. `CAPTCHA_PRE_CHECK_TYPE_UNSPECIFIED` `CHECKBOX`: User must click the "I am not a robot" button. `SLIDER`: User must move the slider from left to right.
challengeType	enum (CaptchaChallengeType) Additional task type of the captcha. `CAPTCHA_CHALLENGE_TYPE_UNSPECIFIED` `IMAGE_TEXT`: Text recognition: The user has to type a distorted text from the picture into a special field. `SILHOUETTES`: Silhouettes: The user has to mark several icons from the picture in a particular order. `KALEIDOSCOPE`: Kaleidoscope: The user has to build a picture from individual parts by shuffling them using a slider.
securityRules[]	SecurityRule List of security rules.
deletionProtection	boolean Determines whether captcha is protected from being deleted.
overrideVariants[]	OverrideVariant List of variants to use in security_rules

SecurityRule

SecurityRule object. Defines the condition and action: when and which variant to show.

Field	Description
name	string Required field. Name of the rule. The name is unique within the captcha. 1-50 characters long.
priority	string (int64) Priority of the rule. Lower value means higher priority.
description	string Optional description of the rule. 0-512 characters long.
condition	Condition The condition for matching the rule.
overrideVariantUuid	string Variant UUID to show in case of match the rule. Keep empty to use defaults.

Condition

Condition object. AND semantics implied.

Field	Description
host	HostMatcher Host where captcha placed.
uri	UriMatcher URI where captcha placed.
headers[]	HeaderMatcher Captcha request headers.
sourceIp	IpMatcher The IP address of the requester.

HostMatcher

HostMatcher object.

Field

Description

hosts[]

StringMatcher

List of hosts. OR semantics implied.

StringMatcher

StringMatcher object.

Field	Description
exactMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
exactNotMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
prefixMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
prefixNotMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
pireRegexMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
pireRegexNotMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.

UriMatcher

UriMatcher object. AND semantics implied.

Field

Description

path

StringMatcher

Path of the URI RFC3986.

queries[]

QueryMatcher

List of query matchers. AND semantics implied.

QueryMatcher

QueryMatcher object.

Field

Description

key

string

Required field. Key of the query parameter.

value

StringMatcher

Required field. Value of the query parameter.

HeaderMatcher

HeaderMatcher object.

Field

Description

name

string

Required field. Name of header (case insensitive).

value

StringMatcher

Required field. Value of the header.

IpMatcher

IpMatcher object. AND semantics implied.

Field	Description
ipRangesMatch	IpRangesMatcher
ipRangesNotMatch	IpRangesMatcher
geoIpMatch	GeoIpMatcher
geoIpNotMatch	GeoIpMatcher

IpRangesMatcher

IpRangesMatcher object.

Field

Description

ipRanges[]

string

List of IP ranges. OR semantics implied.

GeoIpMatcher

GeoIpMatcher object.

Field

Description

locations[]

string

ISO 3166-1 alpha 2. OR semantics implied.

OverrideVariant

OverrideVariant object. Contains the settings to override.

Field	Description
uuid	string Unique identifier of the variant.
description	string Optional description of the rule. 0-512 characters long.
complexity	enum (CaptchaComplexity) Complexity of the captcha. `CAPTCHA_COMPLEXITY_UNSPECIFIED` `EASY`: High chance to pass pre-check and easy advanced challenge. `MEDIUM`: Medium chance to pass pre-check and normal advanced challenge. `HARD`: Little chance to pass pre-check and hard advanced challenge. `FORCE_HARD`: Impossible to pass pre-check and hard advanced challenge.
preCheckType	enum (CaptchaPreCheckType) Basic check type of the captcha. `CAPTCHA_PRE_CHECK_TYPE_UNSPECIFIED` `CHECKBOX`: User must click the "I am not a robot" button. `SLIDER`: User must move the slider from left to right.
challengeType	enum (CaptchaChallengeType) Additional task type of the captcha. `CAPTCHA_CHALLENGE_TYPE_UNSPECIFIED` `IMAGE_TEXT`: Text recognition: The user has to type a distorted text from the picture into a special field. `SILHOUETTES`: Silhouettes: The user has to mark several icons from the picture in a particular order. `KALEIDOSCOPE`: Kaleidoscope: The user has to build a picture from individual parts by shuffling them using a slider.

Response

HTTP Code: 200 - OK

{
  "id": "string",
  "description": "string",
  "createdAt": "string",
  "createdBy": "string",
  "modifiedAt": "string",
  "done": "boolean",
  "metadata": {
    "captchaId": "string"
  },
  // Includes only one of the fields `error`, `response`
  "error": {
    "code": "integer",
    "message": "string",
    "details": [
      "object"
    ]
  },
  "response": {
    "id": "string",
    "folderId": "string",
    "cloudId": "string",
    "clientKey": "string",
    "createdAt": "string",
    "name": "string",
    "allowedSites": [
      "string"
    ],
    "complexity": "string",
    "styleJson": "string",
    "suspend": "boolean",
    "turnOffHostnameCheck": "boolean",
    "preCheckType": "string",
    "challengeType": "string",
    "securityRules": [
      {
        "name": "string",
        "priority": "string",
        "description": "string",
        "condition": {
          "host": {
            "hosts": [
              {
                // Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`
                "exactMatch": "string",
                "exactNotMatch": "string",
                "prefixMatch": "string",
                "prefixNotMatch": "string",
                "pireRegexMatch": "string",
                "pireRegexNotMatch": "string"
                // end of the list of possible fields
              }
            ]
          },
          "uri": {
            "path": {
              // Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`
              "exactMatch": "string",
              "exactNotMatch": "string",
              "prefixMatch": "string",
              "prefixNotMatch": "string",
              "pireRegexMatch": "string",
              "pireRegexNotMatch": "string"
              // end of the list of possible fields
            },
            "queries": [
              {
                "key": "string",
                "value": {
                  // Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`
                  "exactMatch": "string",
                  "exactNotMatch": "string",
                  "prefixMatch": "string",
                  "prefixNotMatch": "string",
                  "pireRegexMatch": "string",
                  "pireRegexNotMatch": "string"
                  // end of the list of possible fields
                }
              }
            ]
          },
          "headers": [
            {
              "name": "string",
              "value": {
                // Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`
                "exactMatch": "string",
                "exactNotMatch": "string",
                "prefixMatch": "string",
                "prefixNotMatch": "string",
                "pireRegexMatch": "string",
                "pireRegexNotMatch": "string"
                // end of the list of possible fields
              }
            }
          ],
          "sourceIp": {
            "ipRangesMatch": {
              "ipRanges": [
                "string"
              ]
            },
            "ipRangesNotMatch": {
              "ipRanges": [
                "string"
              ]
            },
            "geoIpMatch": {
              "locations": [
                "string"
              ]
            },
            "geoIpNotMatch": {
              "locations": [
                "string"
              ]
            }
          }
        },
        "overrideVariantUuid": "string"
      }
    ],
    "deletionProtection": "boolean",
    "overrideVariants": [
      {
        "uuid": "string",
        "description": "string",
        "complexity": "string",
        "preCheckType": "string",
        "challengeType": "string"
      }
    ]
  }
  // end of the list of possible fields
}

An Operation resource. For more information, see Operation.

Field	Description
id	string ID of the operation.
description	string Description of the operation. 0-256 characters long.
createdAt	string (date-time) Creation timestamp. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
createdBy	string ID of the user or service account who initiated the operation.
modifiedAt	string (date-time) The time when the Operation resource was last modified. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
done	boolean If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.
metadata	CreateCaptchaMetadata Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any.
error	Status The error result of the operation in case of failure or cancellation. Includes only one of the fields `error`, `response`. The operation result. If `done == false` and there was no failure detected, neither `error` nor `response` is set. If `done == false` and there was a failure detected, `error` is set. If `done == true`, exactly one of `error` or `response` is set.
response	Captcha The normal response of the operation in case of success. If the original method returns no data on success, such as Delete, the response is google.protobuf.Empty. If the original method is the standard Create/Update, the response should be the target resource of the operation. Any method that returns a long-running operation should document the response type, if any. Includes only one of the fields `error`, `response`. The operation result. If `done == false` and there was no failure detected, neither `error` nor `response` is set. If `done == false` and there was a failure detected, `error` is set. If `done == true`, exactly one of `error` or `response` is set.

CreateCaptchaMetadata

Field

Description

captchaId

string

ID of the captcha that is being created.

Status

The error result of the operation in case of failure or cancellation.

Field	Description
code	integer (int32) Error code. An enum value of google.rpc.Code.
message	string An error message.
details[]	object A list of messages that carry the error details.

Captcha

A Captcha resource.

Field	Description
id	string ID of the captcha.
folderId	string ID of the folder that the captcha belongs to.
cloudId	string ID of the cloud that the captcha belongs to.
clientKey	string Client key of the captcha, see CAPTCHA keys.
createdAt	string (date-time) Creation timestamp in RFC3339 text format. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
name	string Name of the captcha. The name is unique within the folder. 3-63 characters long.
allowedSites[]	string List of allowed host names, see Domain validation.
complexity	enum (CaptchaComplexity) Complexity of the captcha. `CAPTCHA_COMPLEXITY_UNSPECIFIED` `EASY`: High chance to pass pre-check and easy advanced challenge. `MEDIUM`: Medium chance to pass pre-check and normal advanced challenge. `HARD`: Little chance to pass pre-check and hard advanced challenge. `FORCE_HARD`: Impossible to pass pre-check and hard advanced challenge.
styleJson	string JSON with variables to define the captcha appearance. For more details see generated JSON in cloud console.
suspend	boolean Determines that the captcha is currently in restricted mode, see SmartCaptcha restricted mode.
turnOffHostnameCheck	boolean Turn off host name check, see Domain validation.
preCheckType	enum (CaptchaPreCheckType) Basic check type of the captcha. `CAPTCHA_PRE_CHECK_TYPE_UNSPECIFIED` `CHECKBOX`: User must click the "I am not a robot" button. `SLIDER`: User must move the slider from left to right.
challengeType	enum (CaptchaChallengeType) Additional task type of the captcha. `CAPTCHA_CHALLENGE_TYPE_UNSPECIFIED` `IMAGE_TEXT`: Text recognition: The user has to type a distorted text from the picture into a special field. `SILHOUETTES`: Silhouettes: The user has to mark several icons from the picture in a particular order. `KALEIDOSCOPE`: Kaleidoscope: The user has to build a picture from individual parts by shuffling them using a slider.
securityRules[]	SecurityRule List of security rules.
deletionProtection	boolean Determines whether captcha is protected from being deleted.
overrideVariants[]	OverrideVariant List of variants to use in security_rules

SecurityRule

SecurityRule object. Defines the condition and action: when and which variant to show.

Field	Description
name	string Required field. Name of the rule. The name is unique within the captcha. 1-50 characters long.
priority	string (int64) Priority of the rule. Lower value means higher priority.
description	string Optional description of the rule. 0-512 characters long.
condition	Condition The condition for matching the rule.
overrideVariantUuid	string Variant UUID to show in case of match the rule. Keep empty to use defaults.

Condition

Condition object. AND semantics implied.

Field	Description
host	HostMatcher Host where captcha placed.
uri	UriMatcher URI where captcha placed.
headers[]	HeaderMatcher Captcha request headers.
sourceIp	IpMatcher The IP address of the requester.

HostMatcher

HostMatcher object.

Field

Description

hosts[]

StringMatcher

List of hosts. OR semantics implied.

StringMatcher

StringMatcher object.

Field	Description
exactMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
exactNotMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
prefixMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
prefixNotMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
pireRegexMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.
pireRegexNotMatch	string Includes only one of the fields `exactMatch`, `exactNotMatch`, `prefixMatch`, `prefixNotMatch`, `pireRegexMatch`, `pireRegexNotMatch`.

UriMatcher

UriMatcher object. AND semantics implied.

Field

Description

path

StringMatcher

Path of the URI RFC3986.

queries[]

QueryMatcher

List of query matchers. AND semantics implied.

QueryMatcher

QueryMatcher object.

Field

Description

key

string

Required field. Key of the query parameter.

value

StringMatcher

Required field. Value of the query parameter.

HeaderMatcher

HeaderMatcher object.

Field

Description

name

string

Required field. Name of header (case insensitive).

value

StringMatcher

Required field. Value of the header.

IpMatcher

IpMatcher object. AND semantics implied.

Field	Description
ipRangesMatch	IpRangesMatcher
ipRangesNotMatch	IpRangesMatcher
geoIpMatch	GeoIpMatcher
geoIpNotMatch	GeoIpMatcher

IpRangesMatcher

IpRangesMatcher object.

Field

Description

ipRanges[]

string

List of IP ranges. OR semantics implied.

GeoIpMatcher

GeoIpMatcher object.

Field

Description

locations[]

string

ISO 3166-1 alpha 2. OR semantics implied.

OverrideVariant

OverrideVariant object. Contains the settings to override.

Field	Description
uuid	string Unique identifier of the variant.
description	string Optional description of the rule. 0-512 characters long.
complexity	enum (CaptchaComplexity) Complexity of the captcha. `CAPTCHA_COMPLEXITY_UNSPECIFIED` `EASY`: High chance to pass pre-check and easy advanced challenge. `MEDIUM`: Medium chance to pass pre-check and normal advanced challenge. `HARD`: Little chance to pass pre-check and hard advanced challenge. `FORCE_HARD`: Impossible to pass pre-check and hard advanced challenge.
preCheckType	enum (CaptchaPreCheckType) Basic check type of the captcha. `CAPTCHA_PRE_CHECK_TYPE_UNSPECIFIED` `CHECKBOX`: User must click the "I am not a robot" button. `SLIDER`: User must move the slider from left to right.
challengeType	enum (CaptchaChallengeType) Additional task type of the captcha. `CAPTCHA_CHALLENGE_TYPE_UNSPECIFIED` `IMAGE_TEXT`: Text recognition: The user has to type a distorted text from the picture into a special field. `SILHOUETTES`: Silhouettes: The user has to mark several icons from the picture in a particular order. `KALEIDOSCOPE`: Kaleidoscope: The user has to build a picture from individual parts by shuffling them using a slider.

SmartCaptcha API, REST: Captcha.Create

HTTP requestHTTP request

Body parametersBody parameters

SecurityRuleSecurityRule

ConditionCondition

HostMatcherHostMatcher

StringMatcherStringMatcher

UriMatcherUriMatcher

QueryMatcherQueryMatcher

HeaderMatcherHeaderMatcher

IpMatcherIpMatcher

IpRangesMatcherIpRangesMatcher

GeoIpMatcherGeoIpMatcher

OverrideVariantOverrideVariant

ResponseResponse

CreateCaptchaMetadataCreateCaptchaMetadata

StatusStatus

CaptchaCaptcha

SecurityRuleSecurityRule

ConditionCondition

HostMatcherHostMatcher

StringMatcherStringMatcher

UriMatcherUriMatcher

QueryMatcherQueryMatcher

HeaderMatcherHeaderMatcher

IpMatcherIpMatcher

IpRangesMatcherIpRangesMatcher

GeoIpMatcherGeoIpMatcher

OverrideVariantOverrideVariant

Was the article helpful?

HTTP request

Body parameters

SecurityRule

Condition

HostMatcher

StringMatcher

UriMatcher

QueryMatcher

HeaderMatcher

IpMatcher

IpRangesMatcher

GeoIpMatcher

OverrideVariant

Response

CreateCaptchaMetadata

Status

Captcha

SecurityRule

Condition

HostMatcher

StringMatcher

UriMatcher

QueryMatcher

HeaderMatcher

IpMatcher

IpRangesMatcher

GeoIpMatcher

OverrideVariant