# Lists ## Get lists `client.Rules.Lists.List(ctx, query) (*SinglePage[ListsList], error)` **get** `/accounts/{account_id}/rules/lists` Fetches all lists in the account. ### Parameters - `query ListListParams` - `AccountID param.Field[string]` The Account ID for this resource. ### Returns - `type ListsList struct{…}` - `ID string` The unique ID of the list. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `Kind ListsListKind` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `const ListsListKindIP ListsListKind = "ip"` - `const ListsListKindRedirect ListsListKind = "redirect"` - `const ListsListKindHostname ListsListKind = "hostname"` - `const ListsListKindASN ListsListKind = "asn"` - `ModifiedOn 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. - `NumItems float64` The number of items in the list. - `NumReferencingFilters float64` The number of [filters](/api/resources/filters/) referencing the list. - `Description string` An informative summary of the list. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.Rules.Lists.List(context.TODO(), rules.ListListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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(ctx, listID, query) (*ListGetResponse, error)` **get** `/accounts/{account_id}/rules/lists/{list_id}` Fetches the details of a list. ### Parameters - `listID string` The unique ID of the list. - `query ListGetParams` - `AccountID param.Field[string]` The Account ID for this resource. ### Returns - `type ListGetResponse struct{…}` - `ID string` The unique ID of the list. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `Kind ListGetResponseKind` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `const ListGetResponseKindIP ListGetResponseKind = "ip"` - `const ListGetResponseKindRedirect ListGetResponseKind = "redirect"` - `const ListGetResponseKindHostname ListGetResponseKind = "hostname"` - `const ListGetResponseKindASN ListGetResponseKind = "asn"` - `ModifiedOn 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. - `NumItems float64` The number of items in the list. - `NumReferencingFilters float64` The number of [filters](/api/resources/filters/) referencing the list. - `Description string` An informative summary of the list. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) list, err := client.Rules.Lists.Get( context.TODO(), "2c0fc9fa937b11eaa1b71c4d701ab86e", rules.ListGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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.New(ctx, params) (*ListNewResponse, error)` **post** `/accounts/{account_id}/rules/lists` Creates a new list of the specified kind. ### Parameters - `params ListNewParams` - `AccountID param.Field[string]` Path param: The Account ID for this resource. - `Kind param.Field[ListNewParamsKind]` Body param: The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `const ListNewParamsKindIP ListNewParamsKind = "ip"` - `const ListNewParamsKindRedirect ListNewParamsKind = "redirect"` - `const ListNewParamsKindHostname ListNewParamsKind = "hostname"` - `const ListNewParamsKindASN ListNewParamsKind = "asn"` - `Name param.Field[string]` Body param: An informative name for the list. Use this name in filter and rule expressions. - `Description param.Field[string]` Body param: An informative summary of the list. ### Returns - `type ListNewResponse struct{…}` - `ID string` The unique ID of the list. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `Kind ListNewResponseKind` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `const ListNewResponseKindIP ListNewResponseKind = "ip"` - `const ListNewResponseKindRedirect ListNewResponseKind = "redirect"` - `const ListNewResponseKindHostname ListNewResponseKind = "hostname"` - `const ListNewResponseKindASN ListNewResponseKind = "asn"` - `ModifiedOn 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. - `NumItems float64` The number of items in the list. - `NumReferencingFilters float64` The number of [filters](/api/resources/filters/) referencing the list. - `Description string` An informative summary of the list. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) list, err := client.Rules.Lists.New(context.TODO(), rules.ListNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Kind: cloudflare.F(rules.ListNewParamsKindIP), Name: cloudflare.F("list1"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, listID, params) (*ListUpdateResponse, error)` **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` - `AccountID param.Field[string]` Path param: The Account ID for this resource. - `Description param.Field[string]` Body param: An informative summary of the list. ### Returns - `type ListUpdateResponse struct{…}` - `ID string` The unique ID of the list. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `Kind ListUpdateResponseKind` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `const ListUpdateResponseKindIP ListUpdateResponseKind = "ip"` - `const ListUpdateResponseKindRedirect ListUpdateResponseKind = "redirect"` - `const ListUpdateResponseKindHostname ListUpdateResponseKind = "hostname"` - `const ListUpdateResponseKindASN ListUpdateResponseKind = "asn"` - `ModifiedOn 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. - `NumItems float64` The number of items in the list. - `NumReferencingFilters float64` The number of [filters](/api/resources/filters/) referencing the list. - `Description string` An informative summary of the list. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) list, err := client.Rules.Lists.Update( context.TODO(), "2c0fc9fa937b11eaa1b71c4d701ab86e", rules.ListUpdateParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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(ctx, listID, body) (*ListDeleteResponse, error)` **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. - `body ListDeleteParams` - `AccountID param.Field[string]` The Account ID for this resource. ### Returns - `type ListDeleteResponse struct{…}` - `ID string` The unique ID of the list. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) list, err := client.Rules.Lists.Delete( context.TODO(), "2c0fc9fa937b11eaa1b71c4d701ab86e", rules.ListDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 - `type Hostname struct{…}` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `URLHostname string` - `ExcludeExactHostname bool` 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 - `type ListsList struct{…}` - `ID string` The unique ID of the list. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `Kind ListsListKind` The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects). - `const ListsListKindIP ListsListKind = "ip"` - `const ListsListKindRedirect ListsListKind = "redirect"` - `const ListsListKindHostname ListsListKind = "hostname"` - `const ListsListKindASN ListsListKind = "asn"` - `ModifiedOn 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. - `NumItems float64` The number of items in the list. - `NumReferencingFilters float64` The number of [filters](/api/resources/filters/) referencing the list. - `Description string` An informative summary of the list. ### Redirect - `type Redirect struct{…}` The definition of the redirect. - `SourceURL string` - `TargetURL string` - `IncludeSubdomains bool` - `PreservePathSuffix bool` - `PreserveQueryString bool` - `StatusCode RedirectStatusCode` - `const RedirectStatusCode301 RedirectStatusCode = 301` - `const RedirectStatusCode302 RedirectStatusCode = 302` - `const RedirectStatusCode307 RedirectStatusCode = 307` - `const RedirectStatusCode308 RedirectStatusCode = 308` - `SubpathMatching bool` # Bulk Operations ## Get bulk operation status `client.Rules.Lists.BulkOperations.Get(ctx, operationID, query) (*ListBulkOperationGetResponse, error)` **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. - `query ListBulkOperationGetParams` - `AccountID param.Field[string]` The Account ID for this resource. ### Returns - `type ListBulkOperationGetResponse interface{…}` - `type ListBulkOperationGetResponseListsBulkOperationPendingOrRunning struct{…}` - `ID string` The unique operation ID of the asynchronous action. - `Status ListBulkOperationGetResponseListsBulkOperationPendingOrRunningStatus` The current status of the asynchronous operation. - `const ListBulkOperationGetResponseListsBulkOperationPendingOrRunningStatusPending ListBulkOperationGetResponseListsBulkOperationPendingOrRunningStatus = "pending"` - `const ListBulkOperationGetResponseListsBulkOperationPendingOrRunningStatusRunning ListBulkOperationGetResponseListsBulkOperationPendingOrRunningStatus = "running"` - `type ListBulkOperationGetResponseListsBulkOperationCompleted struct{…}` - `ID string` The unique operation ID of the asynchronous action. - `Completed string` The RFC 3339 timestamp of when the operation was completed. - `Status ListBulkOperationGetResponseListsBulkOperationCompletedStatus` The current status of the asynchronous operation. - `const ListBulkOperationGetResponseListsBulkOperationCompletedStatusCompleted ListBulkOperationGetResponseListsBulkOperationCompletedStatus = "completed"` - `type ListBulkOperationGetResponseListsBulkOperationFailed struct{…}` - `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 ListBulkOperationGetResponseListsBulkOperationFailedStatus` The current status of the asynchronous operation. - `const ListBulkOperationGetResponseListsBulkOperationFailedStatusFailed ListBulkOperationGetResponseListsBulkOperationFailedStatus = "failed"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) bulkOperation, err := client.Rules.Lists.BulkOperations.Get( context.TODO(), "4da8780eeb215e6cb7f48dd981c4ea02", rules.ListBulkOperationGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 } ``` # Items ## Get list items `client.Rules.Lists.Items.List(ctx, listID, params) (*CursorPaginationAfter[ListItemListResponse], error)` **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 ListItemListParams` - `AccountID param.Field[string]` Path param: The Account ID for this resource. - `Cursor param.Field[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. - `PerPage param.Field[int64]` Query param: Amount of results to include in each paginated response. A non-negative 32 bit integer. - `Search param.Field[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 - `type ListItemListResponse interface{…}` - `type ListItemListResponseListsListItemIPFull struct{…}` - `ID string` Defines the unique ID of the item in the List. - `CreatedOn 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. - `ModifiedOn string` The RFC 3339 timestamp of when the list was last modified. - `Comment string` Defines an informative summary of the list item. - `type ListItemListResponseListsListItemHostnameFull struct{…}` - `ID string` Defines the unique ID of the item in the List. - `CreatedOn 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 (-). - `URLHostname string` - `ExcludeExactHostname bool` 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. - `ModifiedOn string` The RFC 3339 timestamp of when the list was last modified. - `Comment string` Defines an informative summary of the list item. - `type ListItemListResponseListsListItemRedirectFull struct{…}` - `ID string` Defines the unique ID of the item in the List. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `ModifiedOn string` The RFC 3339 timestamp of when the list was last modified. - `Redirect Redirect` The definition of the redirect. - `SourceURL string` - `TargetURL string` - `IncludeSubdomains bool` - `PreservePathSuffix bool` - `PreserveQueryString bool` - `StatusCode RedirectStatusCode` - `const RedirectStatusCode301 RedirectStatusCode = 301` - `const RedirectStatusCode302 RedirectStatusCode = 302` - `const RedirectStatusCode307 RedirectStatusCode = 307` - `const RedirectStatusCode308 RedirectStatusCode = 308` - `SubpathMatching bool` - `Comment string` Defines an informative summary of the list item. - `type ListItemListResponseListsListItemASNFull struct{…}` - `ID string` Defines the unique ID of the item in the List. - `ASN int64` Defines a non-negative 32 bit integer. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `ModifiedOn string` The RFC 3339 timestamp of when the list was last modified. - `Comment string` Defines an informative summary of the list item. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.Rules.Lists.Items.List( context.TODO(), "2c0fc9fa937b11eaa1b71c4d701ab86e", rules.ListItemListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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(ctx, listID, itemID, query) (*ListItemGetResponse, error)` **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. - `query ListItemGetParams` - `AccountID param.Field[string]` The Account ID for this resource. ### Returns - `type ListItemGetResponse interface{…}` - `type ListItemGetResponseListsListItemIPFull struct{…}` - `ID string` Defines the unique ID of the item in the List. - `CreatedOn 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. - `ModifiedOn string` The RFC 3339 timestamp of when the list was last modified. - `Comment string` Defines an informative summary of the list item. - `type ListItemGetResponseListsListItemHostnameFull struct{…}` - `ID string` Defines the unique ID of the item in the List. - `CreatedOn 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 (-). - `URLHostname string` - `ExcludeExactHostname bool` 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. - `ModifiedOn string` The RFC 3339 timestamp of when the list was last modified. - `Comment string` Defines an informative summary of the list item. - `type ListItemGetResponseListsListItemRedirectFull struct{…}` - `ID string` Defines the unique ID of the item in the List. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `ModifiedOn string` The RFC 3339 timestamp of when the list was last modified. - `Redirect Redirect` The definition of the redirect. - `SourceURL string` - `TargetURL string` - `IncludeSubdomains bool` - `PreservePathSuffix bool` - `PreserveQueryString bool` - `StatusCode RedirectStatusCode` - `const RedirectStatusCode301 RedirectStatusCode = 301` - `const RedirectStatusCode302 RedirectStatusCode = 302` - `const RedirectStatusCode307 RedirectStatusCode = 307` - `const RedirectStatusCode308 RedirectStatusCode = 308` - `SubpathMatching bool` - `Comment string` Defines an informative summary of the list item. - `type ListItemGetResponseListsListItemASNFull struct{…}` - `ID string` Defines the unique ID of the item in the List. - `ASN int64` Defines a non-negative 32 bit integer. - `CreatedOn string` The RFC 3339 timestamp of when the list was created. - `ModifiedOn string` The RFC 3339 timestamp of when the list was last modified. - `Comment string` Defines an informative summary of the list item. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) item, err := client.Rules.Lists.Items.Get( context.TODO(), "2c0fc9fa937b11eaa1b71c4d701ab86e", "34b12448945f11eaa1b71c4d701ab86e", rules.ListItemGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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.New(ctx, listID, params) (*ListItemNewResponse, error)` **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 ListItemNewParams` - `AccountID param.Field[string]` Path param: The Account ID for this resource. - `Body param.Field[[]ListItemNewParamsBody]` Body param - `type ListItemNewParamsBodyListsListItemIPComment struct{…}` - `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. - `type ListItemNewParamsBodyListsListItemRedirectComment struct{…}` - `Redirect Redirect` The definition of the redirect. - `SourceURL string` - `TargetURL string` - `IncludeSubdomains bool` - `PreservePathSuffix bool` - `PreserveQueryString bool` - `StatusCode RedirectStatusCode` - `const RedirectStatusCode301 RedirectStatusCode = 301` - `const RedirectStatusCode302 RedirectStatusCode = 302` - `const RedirectStatusCode307 RedirectStatusCode = 307` - `const RedirectStatusCode308 RedirectStatusCode = 308` - `SubpathMatching bool` - `Comment string` Defines an informative summary of the list item. - `type ListItemNewParamsBodyListsListItemHostnameComment struct{…}` - `Hostname Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `URLHostname string` - `ExcludeExactHostname bool` 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. - `type ListItemNewParamsBodyListsListItemASNComment struct{…}` - `ASN int64` Defines a non-negative 32 bit integer. - `Comment string` Defines an informative summary of the list item. ### Returns - `type ListItemNewResponse struct{…}` - `OperationID string` The unique operation ID of the asynchronous action. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) item, err := client.Rules.Lists.Items.New( context.TODO(), "2c0fc9fa937b11eaa1b71c4d701ab86e", rules.ListItemNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Body: []rules.ListItemNewParamsBodyUnion{rules.ListItemNewParamsBodyListsListItemIPComment{ IP: cloudflare.F("10.0.0.1"), }}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", item.OperationID) } ``` #### 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(ctx, listID, params) (*ListItemUpdateResponse, error)` **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 ListItemUpdateParams` - `AccountID param.Field[string]` Path param: The Account ID for this resource. - `Body param.Field[[]ListItemUpdateParamsBody]` Body param - `type ListItemUpdateParamsBodyListsListItemIPComment struct{…}` - `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. - `type ListItemUpdateParamsBodyListsListItemRedirectComment struct{…}` - `Redirect Redirect` The definition of the redirect. - `SourceURL string` - `TargetURL string` - `IncludeSubdomains bool` - `PreservePathSuffix bool` - `PreserveQueryString bool` - `StatusCode RedirectStatusCode` - `const RedirectStatusCode301 RedirectStatusCode = 301` - `const RedirectStatusCode302 RedirectStatusCode = 302` - `const RedirectStatusCode307 RedirectStatusCode = 307` - `const RedirectStatusCode308 RedirectStatusCode = 308` - `SubpathMatching bool` - `Comment string` Defines an informative summary of the list item. - `type ListItemUpdateParamsBodyListsListItemHostnameComment struct{…}` - `Hostname Hostname` Valid characters for hostnames are ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-). - `URLHostname string` - `ExcludeExactHostname bool` 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. - `type ListItemUpdateParamsBodyListsListItemASNComment struct{…}` - `ASN int64` Defines a non-negative 32 bit integer. - `Comment string` Defines an informative summary of the list item. ### Returns - `type ListItemUpdateResponse struct{…}` - `OperationID string` The unique operation ID of the asynchronous action. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) item, err := client.Rules.Lists.Items.Update( context.TODO(), "2c0fc9fa937b11eaa1b71c4d701ab86e", rules.ListItemUpdateParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Body: []rules.ListItemUpdateParamsBodyUnion{rules.ListItemUpdateParamsBodyListsListItemIPComment{ IP: cloudflare.F("10.0.0.1"), }}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", item.OperationID) } ``` #### 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(ctx, listID, params) (*ListItemDeleteResponse, error)` **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 ListItemDeleteParams` - `AccountID param.Field[string]` Path param: The Account ID for this resource. - `Items param.Field[[]ListItemDeleteParamsItem]` Body param - `ID string` Defines the unique ID of the item in the List. ### Returns - `type ListItemDeleteResponse struct{…}` - `OperationID string` The unique operation ID of the asynchronous action. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/rules" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) item, err := client.Rules.Lists.Items.Delete( context.TODO(), "2c0fc9fa937b11eaa1b71c4d701ab86e", rules.ListItemDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", item.OperationID) } ``` #### 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 - `type ListCursor struct{…}` - `After string` - `Before string` ### List Item - `type ListItem struct{…}` - `OperationID string` The unique operation ID of the asynchronous action.