Clarifying Cloudflare API Filter Operators

Cloudflare's API documentation mentions Optional Filter Operators such as starts_with, ends_with, and contains, but it lacks clear examples of how to use them. This guide explains the correct syntax for these operators and provides working examples to help you filter results effectively.

For the official Cloudflare API documentation, visit: Cloudflare API - List Zones

Correct Syntax for Filter Operators

The correct format to use filter operators in the Cloudflare API is:

parameter=operator:value

For example, to filter zones where the name starts with a specific value, the syntax is:

name=starts_with:<value>

This approach works for operators like contains, starts_with, and ends_with.

Supported Filter Operators

Operator	Description	Example
equal (default)	Exact match	`name=example.com`
not_equal	Not equal to	`name=not_equal:example.com`
starts_with	Name starts with specified value	`name=starts_with:example`
ends_with	Name ends with specified value	`name=ends_with:.com`
contains	Name contains specified value	`name=contains:example`
starts_with_case_sensitive	Case-sensitive starts with	`name=starts_with_case_sensitive:Example`
ends_with_case_sensitive	Case-sensitive ends with	`name=ends_with_case_sensitive:.Com`
contains_case_sensitive	Case-sensitive contains	`name=contains_case_sensitive:Example`

Example Endpoint

The endpoint to list zones in Cloudflare is:

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

You can append the filter operators to refine your search.

Examples of Using Filter Operators

1. Name Contains a String

To fetch all zones where the name contains example:

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=contains:example" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"

2. Name Starts With a String

To fetch all zones where the name starts with example:

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=starts_with:example" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"

3. Name Ends With a String

To fetch all zones where the name ends with .com:

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=ends_with:.com" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"

4. Case-Sensitive Starts With

To fetch all zones where the name case-sensitively starts with Example:

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=starts_with_case_sensitive:Example" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"

Combining Filters with Pagination

You can combine filter operators with pagination parameters like page and per_page:

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=starts_with:example&page=1&per_page=20" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"

Common Pitfalls

Operator Format: Ensure you use operator:value format without spaces.
- Correct: name=starts_with:example
- Incorrect: name[starts_with]=example or name.starts_with=example
URL Encoding: If your values contain special characters, URL-encode them.
API Token Permissions: Ensure your API token has the necessary permissions to fetch zones.

Summary

Cloudflare API's filter operators provide a flexible way to search zones:

Use parameter=operator:value syntax.
Combine filters with pagination for large datasets.

Quick Reference

Filter	Syntax Example
Contains	`name=contains:example`
Starts With	`name=starts_with:example`
Ends With	`name=ends_with:.com`

If you face issues, double-check your syntax and ensure the API token is valid.

Happy coding! 🚀

tomerof/cloudflare-api-v4-filter-operators.md