Skip to content

Make API calls

Last updated View as MarkdownAgent setup

Once you create your API token, all API requests are authorized in the same way. Cloudflare uses the RFC standard ↗ Authorization: Bearer <API_TOKEN> interface. An example request is shown below.

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID" \
--header "Authorization: Bearer YQSn-xWAQiiEh9qM58wZNnyQS7FUdoqGIUAbrh7T"

Never send or store your API token secret in plaintext. Also be sure not to check it into code repositories, especially public ones.

Consider defining environment variables for the zone or account ID, as well as for authentication credentials (for example, the API token).

To format JSON output for readability in the command line, you can use a tool like jq, a command-line JSON processor. For more information on obtaining and installing jq, refer to Download jq ↗.

The following example will format the curl JSON output using jq:

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq .

Using Cloudflare's APIs

Every Cloudflare API element is fixed to a version number. The latest version is Version 4. The stable base URL for all Version 4 HTTPS endpoints is: https://api.cloudflare.com/client/v4/

For specific guidance on making API calls, refer to the following resources:

Query parameters

Several Cloudflare endpoints have optional query parameters to filter incoming results, such as List Zones.

When adding those query parameters, make sure you enclose the URL in double quotes "" (just like the header values), or the API call might error.

curl "https://api.cloudflare.com/client/v4/zones?account.id=$ACCOUNT_ID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

You can enclose strings using either single quotes ('') or double quotes (""). However, using single quotes prevents variable substitution in shells like bash. In the previous example, this would mean that the $ACCOUNT_ID and $CLOUDFLARE_API_TOKEN environment variables would not be replaced with their values.

Pagination

Sometimes there will be too many results to display via the default page size, for example you might receive the following:

"count": 1,
"page": 1,
"per_page": 20,
"total_count": 200,

Two query parameter options exist, which can be combined to paginate across the results.

  • page=x enables you to select a specific page.
  • per_page=xx enables you to adjust the number of results displayed on a page. If you select too many, you may get a timeout.

An example might be https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?per_page=100&page=2.

Other options are:

  • order: Select the attribute to order by.
  • direction: Either ASC (ascending order) or DESC (descending order).

The available options will be listed at the end of the result_info of all endpoints in the API documentation.

Making API calls on Windows

Recent versions of Windows 10 and 11 already include the curl tool ↗ used in the developer documentation's API examples. If you are using a different Windows version, refer to Windows downloads ↗ in the curl website for more information on obtaining and installing this tool.

Using a Command Prompt window

To use the Cloudflare API with curl on a Command Prompt window, you must use double quotes (") as string delimiters.

A typical PATCH request will be similar to the following:

C:\>curl --request PATCH "https://api.cloudflare.com/client/v4/user/invites/{id}" --header "X-Auth-Email: <EMAIL>" --header "X-Auth-Key: <API_KEY>" --data "{""status"": ""accepted""}"

To escape a double quote character in a request body (for example, a body specified with -d or --data in a POST/PATCH request), prepend it with another double quote (") or a backslash (