Cloudflare's Unreleased Rate Limiting Documentation

{
  "id": "/client/zone/rate_limits",
  "title": "Rate Limits for a Zone",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Documentation for Cloudflare Rate Limits",
  "type": "object",
  "allOf": [
    {
      "$ref": "#/definitions/ratelimit"
    }
  ],
  "definitions": {
    "zone_identifier": {
      "$ref": "../../common/zone.json#/definitions/identifier"
    },
    "id": {
      "description": "Ratelimit identifier",
      "type": "string",
      "maxLength": 32,
      "readOnly": true,
      "example": "372e67954025e0ba6aaa6d586b9e0b59"
    },
    "ratelimit": {
      "properties": {
        "id": {
          "$ref": "#/definitions/id"
        },
        "disabled": {
          "type": "boolean",
          "description": "Whether this ratelimit is currently disabled",
          "example": false
        },
        "description": {
          "type": "string",
          "description": "A note that you can use to describe the reason for a rate limit. This value is sanitized and all tags are removed",
          "maxLength": 1024,
          "example": "Prevent multiple login failures to mitigate brute force attacks"
        },
        "match": {
          "type": "object",
          "description": "Determines which traffic the rate limit counts towards the threshold",
          "properties": {
            "request": {
              "type": "object",
              "description": "Matches HTTP requests (from the client to Cloudflare)",
              "properties": {
                "methods": {
                  "type": "array",
                  "description": "HTTP Methods, can be a subset ['POST','PUT'] or all ['_ALL_']",
                  "items": {
                    "type": "string",
                    "description": "HTTP Method, or '_ALL_' to indicate all methods",
                    "example": "GET"
                  },
                  "example": ["GET", "POST"]
                },
                "schemes": {
                  "type": "array",
                  "description": "HTTP Schemes, can be one ['HTTPS'], both ['HTTP','HTTPS'] or all ['_ALL_']",
                  "items": {
                    "type": "string",
                    "description": "HTTP Scheme, or '_ALL_' to indicate all schemes",
                    "example": "HTTPS"
                  },
                  "example": ["HTTP", "HTTPS"]
                },
                "url": {
                  "type": "string",
                  "description": "The URL pattern to match comprised of the host and path, i.e.example.org/path*. Wildcard * are expanded to match applicable traffic, query strings are not matched.",
                  "maxLength": 1024,
                  "example": "*.example.org/path*"
                }
              }
            },
            "response": {
              "type": "object",
              "description": "Matches HTTP responses before they are returned to the client from Cloudflare. If this is defined, then the entire counting of traffic occurs at this stage.",
              "properties": {
                "status": {
                  "type": "array",
                  "description": "HTTP Status codes, can be one [403], many [401,403] or indicate all by not providing this value",
                  "items": {
                    "type": "number",
                    "minimum": 100,
                    "maximum": 999,
                    "description": "HTTP Status code",
                    "example": 401
                  },
                  "example": [401, 403]
                },
                "origin_traffic": {
                  "type": "boolean",
                  "description": "Only count traffic that has come from your origin servers. If true, cached items that Cloudflare serve will not count towards rate limiting.",
                  "example": true
                }
              }
            }
          }
        },
        "threshold": {
          "type": "number",
          "description": "The threshold that triggers the rate limit mitigations, combine with sample_rate. i.e. thresold per sample_rate",
          "minimum": 2,
          "maximum": 1000000,
          "example": 60
        },
        "sample_rate": {
          "type": "number",
          "description": "The time in seconds to count matching traffic. If the count exceeds thresold within this period the action will be performed",
          "minimum": 1,
          "maximum": 86400,
          "example": 900
        },
        "action": {
          "type": "object",
          "description": "The action to be performed when the thresold of matched traffic within the sample_rate period is exceeded",
          "properties": {
            "mode": {
              "type": "string",
              "description": "The type of action to perform, i.e. simulate or ban",
              "maxLength": 10,
              "example": "simulate"
            },
            "timeout": {
              "type": "number",
              "description": "The time in seconds to perform the mitigation action. Must be the same or greater than the sample_rate",
              "minimum": 1,
              "maximum": 86400,
              "example": 86400
            },
            "response": {
              "type": "object",
              "description": "Custom content-type and body to return, this overrides the custom error for the zone",
              "properties": {
                "content_type": {
                  "type": "string",
                  "description": "The content-type of the body, must be one of: text/plain text/xml application/javascript",
                  "maxLength": 50,
                  "example": "text/xml"
                },
                "body": {
                  "type": "string",
                  "description": "The body to return, the content here should conform to the content_type",
                  "maxLength": 10240,
                  "example": "<error>This request has been rate-limited.</error>"
                }
              }
            }
          }
        }
      },
    },
    "ratelimit_response_single": {
      "allOf": [
        {
          "$ref": "../../common/api-response-single.json"
        },
        {
          "type": "object",
          "properties": {
            "result": {
              "type": "object",
              "rel": "self"
            }
          }
        }
      ]
    },
    "ratelimit_response_collection": {
      "allOf": [
        {
          "$ref": "../../common/api-response-collection.json"
        },
        {
          "type": "object",
          "properties": {
            "result": {
              "type": "array",
              "items": {
                "rel": "self"
              }
            }
          }
        }
      ]
    }
  },


  "links": [
    {
      "title": "List rate limits",
      "description": "List, a zones' rate limits.",
      "href": "/zones/{#/definitions/zone_identifier}/rate_limits",
      "method": "GET",
      "plan_availability": {
        "free": true,
        "pro": true,
        "business": true,
        "enterprise": true
      },
      "rel": "search",
      "schema": {
        "type": "object",
        "properties": {
          "page": {
            "type": "number",
            "description": "Page number of paginated results",
            "minimum": 1,
            "default": 1
          },
          "per_page": {
            "type": "number",
            "description": "Number of DNS records per page",
            "minimum": 5,
            "maximum": 100,
            "default": 20
          }
        }
      },
      "targetSchema": {
        "$ref": "#/definitions/ratelimit_response_collection"
      }
    },
    {
      "title": "Create a ratelimit",
      "description": "Create a new rate limit for a zone. See the record object definitions for required attributes for each record type",
      "href": "/zones/{#/definitions/zone_identifier}/rate_limits",
      "method": "POST",
      "plan_availability": {
        "free": true,
        "pro": true,
        "business": true,
        "enterprise": true
      },
      "rel": "create",
      "required": [
        "match",
        "thresold",
        "sample_rate",
        "action"
      ],
      "schema": {
        "type": {
          "$ref": "#/definitions/ratelimit"
        }
      },
      "targetSchema": {
        "$ref": "#/definitions/ratelimit_response_single"
      }
    },
    {
      "title": "Rate limit details",
      "href": "/zones/{#/definitions/zone_identifier}/rate_limits/{#/definitions/id}",
      "method": "GET",
      "plan_availability": {
        "free": true,
        "pro": true,
        "business": true,
        "enterprise": true
      },
      "rel": "self",
      "permissions_required": {
        "enum": [
          "#dns_records:read"
        ]
      },
      "targetSchema": {
        "$ref": "#/definitions/ratelimit_response_single"
      }
    },
    {
      "title": "Update rate limit",
      "href": "/zones/{#/definitions/zone_identifier}/rate_limits/{#/definitions/id}",
      "method": "PUT",
      "plan_availability": {
        "free": true,
        "pro": true,
        "business": true,
        "enterprise": true
      },
      "rel": "update",
      "required": [
        "match",
        "thresold",
        "sample_rate",
        "action"
      ],
      "schema": {
        "type": {
          "$ref": "#/definitions/ratelimit"
        }
      },
      "targetSchema": {
        "$ref": "#/definitions/ratelimit_response_single"
      }
    },
    {
      "title": "Delete rate limit",
      "href": "/zones/{#/definitions/zone_identifier}/rate_limits/{#/definitions/id}",
      "method": "DELETE",
      "plan_availability": {
        "free": true,
        "pro": true,
        "business": true,
        "enterprise": true
      },
      "rel": "destroy",
      "targetSchema": {
        "allOf": [
          {
            "$ref": "#/definitions/ratelimit_response_single"
          },
          {
            "type": "object",
            "properties": {
              "result": {
                "properties": {
                  "ID": {
                    "$ref": "#/definitions/identifier"
                  }
                }
              }
            }
          }
        ]
      }
    }
  ],
  "link_errors": {
    "10000": "Invalid user",
    "10001": "Rate limit not found",
    "10002": "Rate limit not unique (edit the existing rather than adding a new)",
    "10004": "Invalid data submitted",
    "10006": "Auth missing",
    "10007": "Auth corrupt",
    "10008": "Auth expired",
    "10009": "Unauthorized",
    "10010": "Time param not valid",
    "10011": "Pagination results in empty page",
    "10012": "URL Param incorrect format",
    "10013": "Patch values not valid",
    "10014": "Patch operation not valid",
    "10015": "Patch value not valid for given context",
    "10016": "Patch not valid",
  }
}

Example:
curl -X POST "https://api.cloudflare.com/client/v4/zones/5207aada36fd2c12d971c05c4e353e5f/rate_limits" \
-H "X-Auth-Email: [email protected]" \
-H "X-Auth-Key: yourkeygoeshere" \
-H "Content-Type: application/json" \
-d '{
"match": {
"request": {
"methods": [
"_ALL_"
],
"schemes": [
"_ALL_"
],
"url": "*kschwenkler.com/about*"
}
},
"threshold": 50,
"period": 300,
"action": {
"mode": "ban",
"timeout": 600,
"response": {
"content_type": "text/html",
"body": "Rate Limit Exceeded!"
}
}
}'