Endpoints

To invoke a Lists API operation, append the endpoint to the Cloudflare API base URL:

https://api.cloudflare.com/client/v4/

For authentication instructions, refer to Cloudflare's API: Getting Started.

For help with making API calls and paginating results, refer to Make API calls.

Note

The Lists API endpoints require a value for {account_id}.

To retrieve a list of accounts to which you have access, use the List Accounts operation and note the IDs of the accounts you want to manage.

The Lists API supports the operations outlined below. Visit the associated links for examples.

Manage lists

Operation	Endpoint	Notes
Create a list	POST accounts/{account_id}/rules/lists	Creates an empty list
Get lists	GET accounts/{account_id}/rules/lists	Fetch all lists for the account. (This request does not fetch the items in the lists.)
Get a list	GET accounts/{account_id}/rules/lists/{list_id}	Fetches a list by its ID. (This request does not display the items in the list.)
Update a list	PUT accounts/{account_id}/rules/lists/{list_id}	Updates the description of a list. You cannot edit the name or kind, and you cannot update items in a list. To update an item in a list, use the Update all list items operation.
Delete a list	DELETE accounts/{account_id}/rules/lists/{list_id}	Deletes the list, but only when no filters reference it.

Manage items in a list

Nearly all the operations for managing items in a list are asynchronous. When you add or delete a large amount of items to or from a list, there may be a delay before the bulk operation is complete.

Asynchronous list operations return an operation_id, which you can use to monitor the status of an API operation. To monitor the status of an asynchronous operation, use the Get bulk operation status endpoint and specify the ID of the operation you want to monitor.

When you make requests to a list while a bulk operation on that list is in progress, the requests are queued and processed in sequence (first in, first out). Requests for successful asynchronous operations return an HTTP 201 status code.

Get list items

• Operation: Get list items
• Method and endpoints: GET accounts/{account_id}/rules/lists/{list_id}/items[?search={query}]
• Notes:
  • Fetches items in a list (all items, by default).
  • Items are sorted in ascending order.
  • In the case of IP lists, CIDRs are sorted by IP address, then by the subnet mask.
  • To filter returned items, use the optional search query string parameter. For more information, refer to the Get list items API operation.

Get a list item

• Operation: Get a list item
• Method and endpoints: GET accounts/{account_id}/rules/lists/{list_id}/items/{item_id}
• Notes: Fetches an item from a list by ID

Create list items

• Operation: Create list items
• Method and endpoints: POST accounts/{account_id}/rules/lists/{list_id}/items
• Notes:
  • Appends a new item or items to a list.
  • Replaces entries that already exist in the list, does not delete any items.
  • Overwrites the comment of the original item.
  • The response includes an operation_id.

Update all list items

• Operation: Update all list items
• Method and endpoints: PUT accounts/{account_id}/rules/lists/{list_id}/items
• Notes:
  • Deletes all current items in the list and replaces them with items.
  • When items is empty, deletes all items in the list.
  • The response includes an operation_id.

Delete list items

• Operation: Delete list items
• Method and endpoints: DELETE accounts/{account_id}/rules/lists/{list_id}/items
• Notes:
  • Deletes specified list items.
  • The response includes an operation_id.