# Lists ## Get lists `client.rules.lists.list(ListListParamsparams, RequestOptionsoptions?): SinglePage` **get** `/accounts/{account_id}/rules/lists` Fetches all lists in the account. ### Parameters - `params: ListListParams` - `account_id: string` The Account ID for this resource. ### Returns - `ListsList` - `id: string` The unique ID of the list. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `kind: "ip" | "redirect" | "hostname" | "asn"` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `name: string` An informative name for the list. Use this name in filter and rule expressions. - `num_items: number` The number of items in the list. - `num_referencing_filters: number` The number of [filters](/api/resources/filters/) referencing the list. - `description?: string` An informative summary of the list. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const listsList of client.rules.lists.list({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', })) { console.log(listsList.id); } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "2c0fc9fa937b11eaa1b71c4d701ab86e", "created_on": "2020-01-01T08:00:00Z", "kind": "ip", "modified_on": "2020-01-10T14:00:00Z", "name": "list1", "num_items": 10, "num_referencing_filters": 2, "description": "This is a note" } ], "success": true } ``` ## Get a list `client.rules.lists.get(stringlistId, ListGetParamsparams, RequestOptionsoptions?): ListGetResponse` **get** `/accounts/{account_id}/rules/lists/{list_id}` Fetches the details of a list. ### Parameters - `listId: string` The unique ID of the list. - `params: ListGetParams` - `account_id: string` The Account ID for this resource. ### Returns - `ListGetResponse` - `id: string` The unique ID of the list. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `kind: "ip" | "redirect" | "hostname" | "asn"` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `name: string` An informative name for the list. Use this name in filter and rule expressions. - `num_items: number` The number of items in the list. - `num_referencing_filters: number` The number of [filters](/api/resources/filters/) referencing the list. - `description?: string` An informative summary of the list. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const list = await client.rules.lists.get('2c0fc9fa937b11eaa1b71c4d701ab86e', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(list.id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "2c0fc9fa937b11eaa1b71c4d701ab86e", "created_on": "2020-01-01T08:00:00Z", "kind": "ip", "modified_on": "2020-01-10T14:00:00Z", "name": "list1", "num_items": 10, "num_referencing_filters": 2, "description": "This is a note" }, "success": true } ``` ## Create a list `client.rules.lists.create(ListCreateParamsparams, RequestOptionsoptions?): ListCreateResponse` **post** `/accounts/{account_id}/rules/lists` Creates a new list of the specified kind. ### Parameters - `params: ListCreateParams` - `account_id: string` Path param: The Account ID for this resource. - `kind: "ip" | "redirect" | "hostname" | "asn"` Body param: The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `name: string` Body param: An informative name for the list. Use this name in filter and rule expressions. - `description?: string` Body param: An informative summary of the list. ### Returns - `ListCreateResponse` - `id: string` The unique ID of the list. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `kind: "ip" | "redirect" | "hostname" | "asn"` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `name: string` An informative name for the list. Use this name in filter and rule expressions. - `num_items: number` The number of items in the list. - `num_referencing_filters: number` The number of [filters](/api/resources/filters/) referencing the list. - `description?: string` An informative summary of the list. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const list = await client.rules.lists.create({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', kind: 'ip', name: 'list1', }); console.log(list.id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "2c0fc9fa937b11eaa1b71c4d701ab86e", "created_on": "2020-01-01T08:00:00Z", "kind": "ip", "modified_on": "2020-01-10T14:00:00Z", "name": "list1", "num_items": 10, "num_referencing_filters": 2, "description": "This is a note" }, "success": true } ``` ## Update a list `client.rules.lists.update(stringlistId, ListUpdateParamsparams, RequestOptionsoptions?): ListUpdateResponse` **put** `/accounts/{account_id}/rules/lists/{list_id}` Updates the description of a list. ### Parameters - `listId: string` The unique ID of the list. - `params: ListUpdateParams` - `account_id: string` Path param: The Account ID for this resource. - `description?: string` Body param: An informative summary of the list. ### Returns - `ListUpdateResponse` - `id: string` The unique ID of the list. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `kind: "ip" | "redirect" | "hostname" | "asn"` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `name: string` An informative name for the list. Use this name in filter and rule expressions. - `num_items: number` The number of items in the list. - `num_referencing_filters: number` The number of [filters](/api/resources/filters/) referencing the list. - `description?: string` An informative summary of the list. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const list = await client.rules.lists.update('2c0fc9fa937b11eaa1b71c4d701ab86e', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(list.id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "2c0fc9fa937b11eaa1b71c4d701ab86e", "created_on": "2020-01-01T08:00:00Z", "kind": "ip", "modified_on": "2020-01-10T14:00:00Z", "name": "list1", "num_items": 10, "num_referencing_filters": 2, "description": "This is a note" }, "success": true } ``` ## Delete a list `client.rules.lists.delete(stringlistId, ListDeleteParamsparams, RequestOptionsoptions?): ListDeleteResponse` **delete** `/accounts/{account_id}/rules/lists/{list_id}` Deletes a specific list and all its items. ### Parameters - `listId: string` The unique ID of the list. - `params: ListDeleteParams` - `account_id: string` The Account ID for this resource. ### Returns - `ListDeleteResponse` - `id: string` The unique ID of the list. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const list = await client.rules.lists.delete('2c0fc9fa937b11eaa1b71c4d701ab86e', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(list.id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "2c0fc9fa937b11eaa1b71c4d701ab86e" }, "success": true } ``` ## Domain Types ### Hostname - `Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `url_hostname: string` - `exclude_exact_hostname?: boolean` Only applies to wildcard hostnames (e.g., *.example.com). When true (default), only subdomains are blocked. When false, both the root domain and subdomains are blocked. ### Lists List - `ListsList` - `id: string` The unique ID of the list. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `kind: "ip" | "redirect" | "hostname" | "asn"` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `name: string` An informative name for the list. Use this name in filter and rule expressions. - `num_items: number` The number of items in the list. - `num_referencing_filters: number` The number of [filters](/api/resources/filters/) referencing the list. - `description?: string` An informative summary of the list. ### Redirect - `Redirect` The definition of the redirect. - `source_url: string` - `target_url: string` - `include_subdomains?: boolean` - `preserve_path_suffix?: boolean` - `preserve_query_string?: boolean` - `status_code?: 301 | 302 | 307 | 308` - `301` - `302` - `307` - `308` - `subpath_matching?: boolean` ### List Get Response - `ListGetResponse` - `id: string` The unique ID of the list. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `kind: "ip" | "redirect" | "hostname" | "asn"` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `name: string` An informative name for the list. Use this name in filter and rule expressions. - `num_items: number` The number of items in the list. - `num_referencing_filters: number` The number of [filters](/api/resources/filters/) referencing the list. - `description?: string` An informative summary of the list. ### List Create Response - `ListCreateResponse` - `id: string` The unique ID of the list. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `kind: "ip" | "redirect" | "hostname" | "asn"` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `name: string` An informative name for the list. Use this name in filter and rule expressions. - `num_items: number` The number of items in the list. - `num_referencing_filters: number` The number of [filters](/api/resources/filters/) referencing the list. - `description?: string` An informative summary of the list. ### List Update Response - `ListUpdateResponse` - `id: string` The unique ID of the list. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `kind: "ip" | "redirect" | "hostname" | "asn"` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `"ip"` - `"redirect"` - `"hostname"` - `"asn"` - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `name: string` An informative name for the list. Use this name in filter and rule expressions. - `num_items: number` The number of items in the list. - `num_referencing_filters: number` The number of [filters](/api/resources/filters/) referencing the list. - `description?: string` An informative summary of the list. ### List Delete Response - `ListDeleteResponse` - `id: string` The unique ID of the list. # Bulk Operations ## Get bulk operation status `client.rules.lists.bulkOperations.get(stringoperationId, BulkOperationGetParamsparams, RequestOptionsoptions?): BulkOperationGetResponse` **get** `/accounts/{account_id}/rules/lists/bulk_operations/{operation_id}` Gets the current status of an asynchronous operation on a list. The `status` property can have one of the following values: `pending`, `running`, `completed`, or `failed`. If the status is `failed`, the `error` property will contain a message describing the error. ### Parameters - `operationId: string` The unique operation ID of the asynchronous action. - `params: BulkOperationGetParams` - `account_id: string` The Account ID for this resource. ### Returns - `BulkOperationGetResponse = ListsBulkOperationPendingOrRunning | ListsBulkOperationCompleted | ListsBulkOperationFailed` - `ListsBulkOperationPendingOrRunning` - `id: string` The unique operation ID of the asynchronous action. - `status: "pending" | "running"` The current status of the asynchronous operation. - `"pending"` - `"running"` - `ListsBulkOperationCompleted` - `id: string` The unique operation ID of the asynchronous action. - `completed: string` The RFC 3339 timestamp of when the operation was completed. - `status: "completed"` The current status of the asynchronous operation. - `"completed"` - `ListsBulkOperationFailed` - `id: string` The unique operation ID of the asynchronous action. - `completed: string` The RFC 3339 timestamp of when the operation was completed. - `error: string` A message describing the error when the status is `failed`. - `status: "failed"` The current status of the asynchronous operation. - `"failed"` ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const bulkOperation = await client.rules.lists.bulkOperations.get( '4da8780eeb215e6cb7f48dd981c4ea02', { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }, ); console.log(bulkOperation); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "4da8780eeb215e6cb7f48dd981c4ea02", "status": "pending" }, "success": true } ``` ## Domain Types ### Bulk Operation Get Response - `BulkOperationGetResponse = ListsBulkOperationPendingOrRunning | ListsBulkOperationCompleted | ListsBulkOperationFailed` - `ListsBulkOperationPendingOrRunning` - `id: string` The unique operation ID of the asynchronous action. - `status: "pending" | "running"` The current status of the asynchronous operation. - `"pending"` - `"running"` - `ListsBulkOperationCompleted` - `id: string` The unique operation ID of the asynchronous action. - `completed: string` The RFC 3339 timestamp of when the operation was completed. - `status: "completed"` The current status of the asynchronous operation. - `"completed"` - `ListsBulkOperationFailed` - `id: string` The unique operation ID of the asynchronous action. - `completed: string` The RFC 3339 timestamp of when the operation was completed. - `error: string` A message describing the error when the status is `failed`. - `status: "failed"` The current status of the asynchronous operation. - `"failed"` # Items ## Get list items `client.rules.lists.items.list(stringlistId, ItemListParamsparams, RequestOptionsoptions?): CursorPaginationAfter` **get** `/accounts/{account_id}/rules/lists/{list_id}/items` Fetches all the items in the list. ### Parameters - `listId: string` The unique ID of the list. - `params: ItemListParams` - `account_id: string` Path param: The Account ID for this resource. - `cursor?: string` Query param: The pagination cursor. An opaque string token indicating the position from which to continue when requesting the next/previous set of records. Cursor values are provided under `result_info.cursors` in the response. You should make no assumptions about a cursor's content or length. - `per_page?: number` Query param: Amount of results to include in each paginated response. A non-negative 32 bit integer. - `search?: string` Query param: A search query to filter returned items. Its meaning depends on the list type: IP addresses must start with the provided string, hostnames and bulk redirects must contain the string, and ASNs must match the string exactly. ### Returns - `ItemListResponse = ListsListItemIPFull | ListsListItemHostnameFull | ListsListItemRedirectFull | ListsListItemASNFull` - `ListsListItemIPFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `ip: string` An IPv4 address, an IPv4 CIDR, an IPv6 address, or an IPv6 CIDR. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemHostnameFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `hostname: Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `url_hostname: string` - `exclude_exact_hostname?: boolean` Only applies to wildcard hostnames (e.g., *.example.com). When true (default), only subdomains are blocked. When false, both the root domain and subdomains are blocked. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemRedirectFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `redirect: Redirect` The definition of the redirect. - `source_url: string` - `target_url: string` - `include_subdomains?: boolean` - `preserve_path_suffix?: boolean` - `preserve_query_string?: boolean` - `status_code?: 301 | 302 | 307 | 308` - `301` - `302` - `307` - `308` - `subpath_matching?: boolean` - `comment?: string` Defines an informative summary of the list item. - `ListsListItemASNFull` - `id: string` Defines the unique ID of the item in the List. - `asn: number` Defines a non-negative 32 bit integer. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const itemListResponse of client.rules.lists.items.list( '2c0fc9fa937b11eaa1b71c4d701ab86e', { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }, )) { console.log(itemListResponse); } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "34b12448945f11eaa1b71c4d701ab86e", "created_on": "2020-01-01T08:00:00Z", "ip": "10.0.0.1", "modified_on": "2020-01-10T14:00:00Z", "comment": "Private IP address" } ], "success": true, "result_info": { "cursors": { "after": "yyy", "before": "xxx" } } } ``` ## Get a list item `client.rules.lists.items.get(stringlistId, stringitemId, ItemGetParamsparams, RequestOptionsoptions?): ItemGetResponse` **get** `/accounts/{account_id}/rules/lists/{list_id}/items/{item_id}` Fetches a list item in the list. ### Parameters - `listId: string` The unique ID of the list. - `itemId: string` Defines the unique ID of the item in the List. - `params: ItemGetParams` - `account_id: string` The Account ID for this resource. ### Returns - `ItemGetResponse = ListsListItemIPFull | ListsListItemHostnameFull | ListsListItemRedirectFull | ListsListItemASNFull` - `ListsListItemIPFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `ip: string` An IPv4 address, an IPv4 CIDR, an IPv6 address, or an IPv6 CIDR. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemHostnameFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `hostname: Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `url_hostname: string` - `exclude_exact_hostname?: boolean` Only applies to wildcard hostnames (e.g., *.example.com). When true (default), only subdomains are blocked. When false, both the root domain and subdomains are blocked. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemRedirectFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `redirect: Redirect` The definition of the redirect. - `source_url: string` - `target_url: string` - `include_subdomains?: boolean` - `preserve_path_suffix?: boolean` - `preserve_query_string?: boolean` - `status_code?: 301 | 302 | 307 | 308` - `301` - `302` - `307` - `308` - `subpath_matching?: boolean` - `comment?: string` Defines an informative summary of the list item. - `ListsListItemASNFull` - `id: string` Defines the unique ID of the item in the List. - `asn: number` Defines a non-negative 32 bit integer. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const item = await client.rules.lists.items.get( '2c0fc9fa937b11eaa1b71c4d701ab86e', '34b12448945f11eaa1b71c4d701ab86e', { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }, ); console.log(item); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "34b12448945f11eaa1b71c4d701ab86e", "created_on": "2020-01-01T08:00:00Z", "ip": "10.0.0.1", "modified_on": "2020-01-10T14:00:00Z", "comment": "Private IP address" }, "success": true } ``` ## Create list items `client.rules.lists.items.create(stringlistId, ItemCreateParamsparams, RequestOptionsoptions?): ItemCreateResponse` **post** `/accounts/{account_id}/rules/lists/{list_id}/items` Appends new items to the list. This operation is asynchronous. To get current the operation status, invoke the `Get bulk operation status` endpoint with the returned `operation_id`. There is a limit of 1 pending bulk operation per account. If an outstanding bulk operation is in progress, the request will be rejected. ### Parameters - `listId: string` The unique ID of the list. - `params: ItemCreateParams` - `account_id: string` Path param: The Account ID for this resource. - `body: Array` Body param - `ListsListItemIPComment` - `ip: string` An IPv4 address, an IPv4 CIDR, an IPv6 address, or an IPv6 CIDR. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemRedirectComment` - `redirect: Redirect` The definition of the redirect. - `source_url: string` - `target_url: string` - `include_subdomains?: boolean` - `preserve_path_suffix?: boolean` - `preserve_query_string?: boolean` - `status_code?: 301 | 302 | 307 | 308` - `301` - `302` - `307` - `308` - `subpath_matching?: boolean` - `comment?: string` Defines an informative summary of the list item. - `ListsListItemHostnameComment` - `hostname: Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `url_hostname: string` - `exclude_exact_hostname?: boolean` Only applies to wildcard hostnames (e.g., *.example.com). When true (default), only subdomains are blocked. When false, both the root domain and subdomains are blocked. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemASNComment` - `asn: number` Defines a non-negative 32 bit integer. - `comment?: string` Defines an informative summary of the list item. ### Returns - `ItemCreateResponse` - `operation_id: string` The unique operation ID of the asynchronous action. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const item = await client.rules.lists.items.create('2c0fc9fa937b11eaa1b71c4d701ab86e', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', body: [{ ip: '10.0.0.1' }], }); console.log(item.operation_id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "operation_id": "4da8780eeb215e6cb7f48dd981c4ea02" }, "success": true } ``` ## Update all list items `client.rules.lists.items.update(stringlistId, ItemUpdateParamsparams, RequestOptionsoptions?): ItemUpdateResponse` **put** `/accounts/{account_id}/rules/lists/{list_id}/items` Removes all existing items from the list and adds the provided items to the list. This operation is asynchronous. To get current the operation status, invoke the `Get bulk operation status` endpoint with the returned `operation_id`. There is a limit of 1 pending bulk operation per account. If an outstanding bulk operation is in progress, the request will be rejected. ### Parameters - `listId: string` The unique ID of the list. - `params: ItemUpdateParams` - `account_id: string` Path param: The Account ID for this resource. - `body: Array` Body param - `ListsListItemIPComment` - `ip: string` An IPv4 address, an IPv4 CIDR, an IPv6 address, or an IPv6 CIDR. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemRedirectComment` - `redirect: Redirect` The definition of the redirect. - `source_url: string` - `target_url: string` - `include_subdomains?: boolean` - `preserve_path_suffix?: boolean` - `preserve_query_string?: boolean` - `status_code?: 301 | 302 | 307 | 308` - `301` - `302` - `307` - `308` - `subpath_matching?: boolean` - `comment?: string` Defines an informative summary of the list item. - `ListsListItemHostnameComment` - `hostname: Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `url_hostname: string` - `exclude_exact_hostname?: boolean` Only applies to wildcard hostnames (e.g., *.example.com). When true (default), only subdomains are blocked. When false, both the root domain and subdomains are blocked. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemASNComment` - `asn: number` Defines a non-negative 32 bit integer. - `comment?: string` Defines an informative summary of the list item. ### Returns - `ItemUpdateResponse` - `operation_id: string` The unique operation ID of the asynchronous action. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const item = await client.rules.lists.items.update('2c0fc9fa937b11eaa1b71c4d701ab86e', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', body: [{ ip: '10.0.0.1' }], }); console.log(item.operation_id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "operation_id": "4da8780eeb215e6cb7f48dd981c4ea02" }, "success": true } ``` ## Delete list items `client.rules.lists.items.delete(stringlistId, ItemDeleteParamsparams, RequestOptionsoptions?): ItemDeleteResponse` **delete** `/accounts/{account_id}/rules/lists/{list_id}/items` Removes one or more items from a list. This operation is asynchronous. To get current the operation status, invoke the `Get bulk operation status` endpoint with the returned `operation_id`. There is a limit of 1 pending bulk operation per account. If an outstanding bulk operation is in progress, the request will be rejected. ### Parameters - `listId: string` The unique ID of the list. - `params: ItemDeleteParams` - `account_id: string` Path param: The Account ID for this resource. - `items?: Array` Body param - `id: string` Defines the unique ID of the item in the List. ### Returns - `ItemDeleteResponse` - `operation_id: string` The unique operation ID of the asynchronous action. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const item = await client.rules.lists.items.delete('2c0fc9fa937b11eaa1b71c4d701ab86e', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(item.operation_id); ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "operation_id": "4da8780eeb215e6cb7f48dd981c4ea02" }, "success": true } ``` ## Domain Types ### List Cursor - `ListCursor` - `after?: string` - `before?: string` ### List Item - `ListItem` - `operation_id: string` The unique operation ID of the asynchronous action. ### Item List Response - `ItemListResponse = ListsListItemIPFull | ListsListItemHostnameFull | ListsListItemRedirectFull | ListsListItemASNFull` - `ListsListItemIPFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `ip: string` An IPv4 address, an IPv4 CIDR, an IPv6 address, or an IPv6 CIDR. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemHostnameFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `hostname: Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `url_hostname: string` - `exclude_exact_hostname?: boolean` Only applies to wildcard hostnames (e.g., *.example.com). When true (default), only subdomains are blocked. When false, both the root domain and subdomains are blocked. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemRedirectFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `redirect: Redirect` The definition of the redirect. - `source_url: string` - `target_url: string` - `include_subdomains?: boolean` - `preserve_path_suffix?: boolean` - `preserve_query_string?: boolean` - `status_code?: 301 | 302 | 307 | 308` - `301` - `302` - `307` - `308` - `subpath_matching?: boolean` - `comment?: string` Defines an informative summary of the list item. - `ListsListItemASNFull` - `id: string` Defines the unique ID of the item in the List. - `asn: number` Defines a non-negative 32 bit integer. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. ### Item Get Response - `ItemGetResponse = ListsListItemIPFull | ListsListItemHostnameFull | ListsListItemRedirectFull | ListsListItemASNFull` - `ListsListItemIPFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `ip: string` An IPv4 address, an IPv4 CIDR, an IPv6 address, or an IPv6 CIDR. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemHostnameFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `hostname: Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `url_hostname: string` - `exclude_exact_hostname?: boolean` Only applies to wildcard hostnames (e.g., *.example.com). When true (default), only subdomains are blocked. When false, both the root domain and subdomains are blocked. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. - `ListsListItemRedirectFull` - `id: string` Defines the unique ID of the item in the List. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `redirect: Redirect` The definition of the redirect. - `source_url: string` - `target_url: string` - `include_subdomains?: boolean` - `preserve_path_suffix?: boolean` - `preserve_query_string?: boolean` - `status_code?: 301 | 302 | 307 | 308` - `301` - `302` - `307` - `308` - `subpath_matching?: boolean` - `comment?: string` Defines an informative summary of the list item. - `ListsListItemASNFull` - `id: string` Defines the unique ID of the item in the List. - `asn: number` Defines a non-negative 32 bit integer. - `created_on: string` The RFC 3339 timestamp of when the list was created. - `modified_on: string` The RFC 3339 timestamp of when the list was last modified. - `comment?: string` Defines an informative summary of the list item. ### Item Create Response - `ItemCreateResponse` - `operation_id: string` The unique operation ID of the asynchronous action. ### Item Update Response - `ItemUpdateResponse` - `operation_id: string` The unique operation ID of the asynchronous action. ### Item Delete Response - `ItemDeleteResponse` - `operation_id: string` The unique operation ID of the asynchronous action.