Cloudflare Docs
WAF
Visit WAF on GitHub
Set theme to dark (⇧+D)

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|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, 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

A fully populated JSON object for an IP 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"
}

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"
}

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 IP Lists.

Any of these formats can exist in the same IP List:

  • 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.

Applies only to IP Lists.

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.

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.