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:

Property	Description	Constraints
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:

Property	Description	Constraints
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 address IPv4 ranges as /8 through /32 CIDRs IPv6 ranges as /12 through /128 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.