Custom Rules API

Can I create custom rules using an API?

Access Control allows you to whitelist and/or blacklist specific bots, IP addresses, and access methods according to customized rules.
Custom Rules can contain multiple conditions and categories. Only when all of the rules conditions match (using the AND operator) the action (whitelist/blacklist/hard block) is executed.

The Custom Rules API allows you to configure whitelisting and blacklisting rules via API calls.

For more information on configuring Access Control and Custom Rules, see Access Control.

Requests

Requests must be sent over HTTPS using a content type of application/json and include the Authorization header that is used for authentication.

Header

Description

Authorization

Token to provide authentication

Content-Type

Value is always application/json

All requests are made to the base URL of https://console.perimeterx.com/api/v1/custom_rules

Authentication

In order to access the PerimeterX Custom Rules API, you are required to present an authentication token in the HTTP Authorization header.

The following is an example:

Authorization: Bearer <TOKEN>

Authentication tokens can be generated in the PerimeterX Portal (https://console.perimeterx.com/). For more information see Managing Applications .

Endpoints

Create custom rule

Parameters

Parameter

Description

description

rule description

type

["none", "blacklist", "whitelist", "hardblock"]

conditions

list of conditions

Request Schema

{
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024
      },
      "type": {
        "enum": ["none", "blacklist", "whitelist", "hardblock"]
      },
      "conditions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "category": {
              "enum": ["ua", "ips", "ipRanges", "domain", "trueIps", "trueIpRanges", "url", "custom_param1", "custom_param2", "custom_param3", "custom_param4", "custom_param5", "custom_param6", "custom_param7", "custom_param8", "custom_param9", "custom_param10"]
            },
            "value": {
              "type": [
                "string",
                "object"
              ],
              "properties": {
                "option": {
                  "enum": ["prefix", "exact", "suffix", "contains", "regex"]
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "option",
                "value"
              ]
            }
          }
        }
      }
    },
    "required": [
      "description",
      "type",
      "conditions"
    ]
  }

Request Example

curl -X POST
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       -d '{
        "description": "custom rule description",
        "type": "blacklist",
        "conditions": [{"category":"ips","value":"1.1.1.1"},{"category":"domain","value":{"option":"exact","value":"example.com"}}]
        }'
        "https://console.perimeterx.com/api/v1/custom_rules"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "custom rule description",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        }
      ]
    },
    "message": "success"
  }

Update custom rule by rule id

Parameters

Parameter

Description

rule_id
(query)

Rule ID.
This can be obtained from the Portal Policy section

description

rule description

type

["none", "blacklist", "whitelist", "hardblock"]

conditions

list of conditions

Request Schema

{
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024
      },
      "type": {
        "enum": ["none", "blacklist", "whitelist", "hardblock"]
      },
      "conditions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "category": {
              "enum": ["ua", "ips", "ipRanges", "domain", "socketIps", "socketIpRanges", "url", "custom_param1", "custom_param2", "custom_param3", "custom_param4", "custom_param5", "custom_param6", "custom_param7", "custom_param8", "custom_param9", "custom_param10"]
            },
            "value": {
              "type": [
                "string",
                "object"
              ],
              "properties": {
                "option": {
                  "enum": ["prefix", "exact", "suffix", "contains", "regex"]
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "option",
                "value"
              ]
            }
          }
        }
      }
    },
    "required": [
      "description",
      "type",
      "conditions"
    ]
  }

Request Example

curl -X POST
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       -d '{
        "description": "updated custom rule description",
        "type": "blacklist",
        "conditions": [{"category":"ips","value":"1.1.1.1"},{"category":"domain","value":{"option":"exact","value":"example.com"}}]
        }'
        "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "updated custom rule description",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        }
      ]
    },
    "message": "success"
  }

Delete custom rule by rule id

Parameters

Parameter

Description

rule_id

Rule ID. It can be obtained from portal policy view

Request Example

curl -X DELETE
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "string"
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": "success",
    "message": "success"
  }

Parameters

Parameter

Description

rule_id

Rule ID. It can be obtained from portal policy view

Request Example

curl -X GET
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "custom rule 1",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ua",
          "value": "PhantomJS"
        },
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        },
        {
          "category": "custom_param1",
          "value": "test"
        }
      ]
    },
    "message": "success"
  }

Get all custom rules

Request Example

.. code-block:: shell

curl -X GET
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "conditions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "category": {
                    "type": "string"
                  },
                  "value": {
                    "type": [
                      "string",
                      "object"
                    ],
                    "properties": {
                      "option": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "option",
                      "value"
                    ]
                  }
                }
              }
            }
          },
          "required": [
            "id",
            "description",
            "type",
            "conditions"
          ]
        }
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": [
      {
        "id": "a596bc02-1189-48b1-9cf2-12001495754e",
        "description": "custom rule 1",
        "type": "blacklist",
        "conditions": [
          {
            "category": "ua",
            "value": "PhantomJS"
          },
          {
            "category": "ips",
            "value": "1.1.1.1"
          },
          {
            "category": "domain",
            "value": {
              "option": "exact",
              "value": "example.com"
            }
          }
        ]
      },
      {
        "id": "46a49376-042d-4ccd-96e4-4f753a6d0930",
        "description": "custom rule 2",
        "type": "none",
        "conditions": [
          {
            "category": "ips",
            "value": "2.2.2.2"
          }
        ]
      }
    ],
    "message": "success"
  }

Error Messages and Codes

The Custom rules API returns error messages in JSON format.

Example

{
    "result": false,
    "message": "Invalid authorization token"
  }

The following table describes the codes which may appear when working with the API.

Status Code

Text

Description

400

Request object not valid

The request structure may be invalid

400

Invalid request

The request structure may be invalid

400

Invalid authorization Token

The Authorization header : Bearer is missing or invalid

400

Custom rule id does not exist

Custom rule id does not exist

400

Custom rule has invalid value

Custom rule id is not a valid UUID

400

Description field value is missing

Description has no value (mandatory field)

400

Type field value is missing

Type has no value (mandatory field)


Did this page help you?