Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 40 additions & 19 deletions src/content/docs/waf/tools/lists/lists-api/endpoints.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,44 +3,65 @@ title: Endpoints
pcx_content_type: reference
sidebar:
order: 2

---

To invoke a [Lists API](/api/resources/rules/subresources/lists/) 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](/fundamentals/api/get-started/).
For authentication instructions, refer to [Cloudflare's API: Get started](/fundamentals/api/get-started/).

For help with making API calls and paginating results, refer to [Make API calls](/fundamentals/api/how-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](/api/resources/accounts/methods/list/) 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

### Create a list

- **Operation**: [Create a list](/api/resources/rules/subresources/lists/methods/create/)
- **Method and endpoint**: `POST accounts/{account_id}/rules/lists`
- **Notes**: Creates an empty list.

## Manage lists
### Get lists

| Operation | Endpoint | Notes |
| --- | --- | --- |
| [Create a list](/api/resources/rules/subresources/lists/methods/create/) | `POST accounts/{account_id}/rules/lists` | Creates an empty list |
| [Get lists](/api/resources/rules/subresources/lists/methods/list/) | `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](/api/resources/rules/subresources/lists/methods/get/) | `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](/api/resources/rules/subresources/lists/methods/update/) | `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](/api/resources/rules/subresources/lists/subresources/items/methods/update/) operation. |
| [Delete a list](/api/resources/rules/subresources/lists/methods/delete/) | `DELETE accounts/{account_id}/rules/lists/{list_id}` | Deletes the list, but only when no filters reference it. |
- **Operation**: [Get lists](/api/resources/rules/subresources/lists/methods/list/)
- **Method and endpoint**: `GET accounts/{account_id}/rules/lists`
- **Notes**:
- Fetches all lists for the account.
- This request does not fetch the items in the lists.

## Manage items in a list
### Get a list

- **Operation**: [Get a list](/api/resources/rules/subresources/lists/methods/get/)
- **Method and endpoint**: `GET accounts/{account_id}/rules/lists/{list_id}`
- **Notes**:
- Fetches a list by its ID.
- This request does not display the items in the list.

### Update a list

- **Operation**: [Update a list](/api/resources/rules/subresources/lists/methods/update/)
- **Method and endpoint**: `PUT accounts/{account_id}/rules/lists/{list_id}`
- **Notes**:
- 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](#update-all-list-items) operation.

### Delete a list

- **Operation**: [Delete a list](/api/resources/rules/subresources/lists/methods/delete/)
- **Method and endpoint**: `DELETE accounts/{account_id}/rules/lists/{list_id}`
- **Notes**: Deletes the list, but only when no [filters](/firewall/api/cf-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.

Expand All @@ -51,7 +72,7 @@ When you make requests to a list while a bulk operation on that list is in progr
### Get list items

- **Operation**: [Get list items](/api/resources/rules/subresources/lists/subresources/items/methods/list/)
- **Method and endpoints**: `GET accounts/{account_id}/rules/lists/{list_id}/items[?search={query}]`
- **Method and endpoint**: `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.
Expand All @@ -61,13 +82,13 @@ When you make requests to a list while a bulk operation on that list is in progr
### Get a list item

- **Operation**: [Get a list item](/api/resources/rules/subresources/lists/subresources/items/methods/get/)
- **Method and endpoints**: `GET accounts/{account_id}/rules/lists/{list_id}/items/{item_id}`
- **Method and endpoint**: `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](/api/resources/rules/subresources/lists/subresources/items/methods/create/)
- **Method and endpoints**: `POST accounts/{account_id}/rules/lists/{list_id}/items`
- **Method and endpoint**: `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.
Expand All @@ -77,7 +98,7 @@ When you make requests to a list while a bulk operation on that list is in progr
### Update all list items

- **Operation**: [Update all list items](/api/resources/rules/subresources/lists/subresources/items/methods/update/)
- **Method and endpoints**: `PUT accounts/{account_id}/rules/lists/{list_id}/items`
- **Method and endpoint**: `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.
Expand All @@ -86,7 +107,7 @@ When you make requests to a list while a bulk operation on that list is in progr
### Delete list items

- **Operation**: [Delete list items](/api/resources/rules/subresources/lists/subresources/items/methods/delete/)
- **Method and endpoints**: `DELETE accounts/{account_id}/rules/lists/{list_id}/items`
- **Method and endpoint**: `DELETE accounts/{account_id}/rules/lists/{list_id}/items`
- **Notes**:
- Deletes specified list items.
- The response includes an `operation_id`.
- The response includes an `operation_id`.
Loading