Cloudflare Docs
Cloudflare Fundamentals
Cloudflare Docs
Cloudflare Fundamentals
GitHub icon
Visit Cloudflare Fundamentals on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Cloudflare Fundamentals
  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|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.