Cloudflare Docs
WAF
Cloudflare Docs
WAF
GitHub icon
Edit this page on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. WAF
  3. ...
  4. ...
  5. Lists API
  6. JSON object

List JSON object

​​ List object structure and properties

A JSON response for the Lists API has this structure:

{
  "id": "2c0fc9fa937b11eaa1b71c4d701ab86e",
  "name": "my_list_name",
  "description": "List description.",
  "kind": "(ip|hostname|asn|redirect)",
  "num_items": 10,
  "num_referencing_filters": 2,
  "created_on": "2021-01-01T08:00:00Z",
  "modified_on": "2021-01-10T14:00:00Z"

}

This table summarizes the object properties:

PropertyDescriptionConstraints
id
String		A UUIDv4 identifier generated by Cloudflare.

Unique, read only.

Length: 32 characters.

name
String		An informative name for the list.

Maximum length: 50 characters.

Only alphanumeric and underscore (_) characters are valid.

A valid name satisfies this regular expression: ^[a-zA-Z0-9_]+$.

description
String		An informative summary of the list.Maximum length: 500 characters.
kind
String		The type of data in the list.Valid values: ip, hostname, asn, redirect.
num_items
Number		The number of items in the list.Read only.
num_referencing_filters
Number		The number of filters that reference this list.Read only.
created_on
String		The RFC 3339 timestamp the list was created.Read only.
modified_on
String		The RFC 3339 timestamp when the list was last modified.Read only.

​​ List item object structure and properties

Each list type (IP address, hostname, ASN, redirects) can only contain items of the same type.

​​ IP address

A fully populated JSON object for an IP address list item has the following structure:

{
  "id": "7c5dae5552338874e5053f2534d2767a",
  "ip": "10.0.0.1/32",
  "comment": "CF DNS server",
  "created_on": "2021-10-01T05:20:00.12345Z",
  "modified_on": "2021-10-01T05:20:00.12345Z"

}

​​ Hostname

A fully populated JSON object for a hostname list item has the following structure:

{
  "id": "7c5dae5552338874e5053f2534d2767a",
  "hostname": {
    "url_hostname": "*.example.com"
  },
  "created_on": "2021-10-11T12:39:02Z",
  "modified_on": "2021-10-11T12:39:02Z"

}

​​ ASN

A fully populated JSON object for an ASN list item has the following structure:

{
  "id": "7c5dae5552338874e5053f2534d2767a",
  "asn": 13335,
  "comment": "My provider's ASN",
  "created_on": "2021-10-11T12:39:02Z",
  "modified_on": "2021-10-11T12:39:02Z"

}

​​ URL redirect

A fully populated JSON object for a Bulk Redirect List item has the following structure:

{
  "id": "7c5dae5552338874e5053f2534d2767a",
  "redirect": {
    "source_url": "https://example.com/blog",
    "target_url": "https://example.com/blog/latest",
    "status_code": 301,
    "include_subdomains": false,
    "subpath_matching": false,
    "preserve_query_string": false,
    "preserve_path_suffix": true
  },
  "created_on": "2021-10-11T12:39:02Z",
  "modified_on": "2021-10-11T12:39:02Z"

}

​​ Properties reference

The JSON object properties for a list item are defined as follows:

PropertyDescriptionConstraints
id
String		A UUIDv4 identifier generated by Cloudflare.

Unique, read only.

Length: 32 characters.

ip
String		An IP address or CIDR range.

Applies only to custom lists with IP addresses (IP lists).

Any of these formats can exist in the same custom list with IP addresses:

  • IPv4 address
  • IPv6 (up to /64) address
  • IPv4 ranges as /32 through /2 CIDRs
  • IPv6 ranges as /64 through /4 CIDRs
comment
String		An informative summary of the item.

Maximum length: 500 characters.

redirect
Object		An object that contains the definition of a URL redirect. Refer to URL redirect parameters for details.

Applies only to Bulk Redirect Lists.

hostname
Object		An object containing a url_hostname property with a hostname value. Refer to Lists with hostnames for details on the supported hostname values.

Applies only to custom lists with hostnames.

asn
Integer		An ASN value.Applies only to custom lists with ASNs.
created_on
String		The RFC 3339 timestamp when the list was created.Read only.
modified_on
String		The RFC 3339 timestamp when the item was last modified.Read only.

For a detailed specification, refer to the Lists API documentation.